企业官网建设流程全解析

TinyPro v1.4.0 像是给一直用着旧版本的人来了一针强心剂。我刚拿到更新日志时最关注的就是 Spring Boot 支持和移动端适配，这两个能力对中后台项目来说太刚需了。以前用 TinyPro 做前端界面，总得在后端接口和权限这块自己拼凑，这次直接把整个链路拉通了。如果你正好在搭一个基于 Spring Boot 的管理系统，或者想把原有后台搬到手机上用，这个版本值得认真看一下。

我升级完第一感觉是“终于不再只是前端模板了”。TinyPro 本来就是一套开源的中后台前端解决方案，把登录页、权限路由、国际化、暗黑模式这些通用能力都做好了，开发者拿过来改改就能用。但在实际业务里，光有页面还不够，后端怎么接入、移动端怎么适配、复杂业务表单怎么落地，这些问题如果不解决，前端框架做得再漂亮也只是花架子。v1.4.0 就是在补齐这些短板，下面我从实际使用的角度拆一拆。

1. 为什么这个版本值得关注：一次补齐后端和终端的双重短板

1.1 TinyPro 是什么，它解决什么问题

TinyPro 的核心价值是“少写重复代码”。做后台管理系统的人都有体会，每一套后台的骨架都差不多：用户登录、Token 校验、菜单权限、列表页、表单页、表格筛选、状态切换。你要是每个项目都从头写，光这些公共部分就得耗掉两三个星期。TinyPro 把这部分沉淀成了一套现成的工程模板，技术栈覆盖 React 和 Vue，页面模块划分清晰，拿来就能跑。

不过，以前用 TinyPro 有一个坑：它默认对接的是 Mock 数据，真正要接后端接口的时候，得自己设计一套请求封装、统一错误码、状态码映射。小项目还好，一旦团队多人并行开发，接口定义各写各的，联调时乱七八糟。v1.4.0 专门做了 Spring Boot 适配层，把前后端接口契约标准化了。

1.2 Spring Boot 支持背后的真正价值

Spring Boot 在国内的普及率非常高，尤其电商、进货销存、企业信息化这些场景，后端接口十有八九是 Spring Boot。TinyPro 支持 Spring Boot，等于是把前端工程和后端工程之间那条“暗沟”填平了。具体来说，它预设了标准的 RESTful 接口返回格式、分页参数、Token 传递方式和权限字段映射。你在后端写接口时，只要按照约定的结构返回，前端就能直接解析。

我特别欣赏它对 Spring Boot 版本的包容度。现在很多项目还在用 Spring Boot 2.3.x、2.6.x，也有不少新项目已经升到 3.x。TinyPro 的对接方案不会强制 bind 某一个版本，而是一套兼容性很好的回调机制。前后端分别部署，通过约定的接口路径通信，这样后端升级 Spring Boot 版本时，前端基本不用动。

1.3 移动端适配：从能用变成好用

很多管理后台的移动端适配，就是把 PC 页面缩小到手机屏幕里看，点按钮得放大才能按。TinyPro v1.4.0 的适配策略不是缩放，而是重构。侧边栏会变成抽屉式导航，表格会自动切换成卡片列表，表单的按钮区会变成固定在底部的操作栏。这明显是考虑了真实使用场景：移动端管理后台通常是给老板看数据、给运营审批工单、给仓管扫码核对，这些操作必须够大够顺手。

对我这种长期做后台的人来说，最惊喜的是它把表格和列表的切换做到了“无痛”。同一个页面，桌面端展示的是标准表格，平板端缩窄列宽，手机端变成卡片流。这套逻辑不是靠 CSS 强行缩放，而是通过响应式组件和断点检测动态调整渲染方式，交互体验差距非常大。

2. 核心更新拆解：Spring Boot 集成不是“加个依赖”那么简单

2.1 集成方式与工程结构建议

先说集成路径。TinyPro 与 Spring Boot 结合，常见有三种方案，我实际用下来的建议如下：

• 前后端完全分离：前端独立部署到 Nginx，后端 Spring Boot 跑在独立服务上，通过 API 网关或跨域配置联通。这是最推荐的方式，前后端团队边界清晰，构建、发布的节奏互不干扰。
• 后端嵌入前端静态资源：把 TinyPro 构建后的 dist 文件放进 Spring Boot 的src/main/resources/static目录，后端启动后直接访问同一端口。适合小型内网工具，但每次前端发布都要重新打包后端，很烦。
• 统一网关路由：如果公司已经有 Spring Cloud Gateway，可以把/api/**路由到后端微服务，把/admin/**路由到前端静态资源。这种模式对多环境切换最友好，TinyPro 里的环境配置只需要改一个网关地址。

我现在的项目采用的是第一种，Maven 工程结构大致是这样：

my-application/ ├── frontend/ # TinyPro 前端工程 │ ├── src/ │ ├── package.json │ └── .env.production ├── backend/ # Spring Boot 后端工程 │ ├── src/main/java/ │ └── src/main/resources/ └── deploy/ ├── nginx.conf └── docker-compose.yml

TinyPro 的request工具默认把/api作为前缀，后端application.yml里设置server.servlet.context-path=/api即可无缝对接。我建议 Nginx 这样转发：

location /api/ { proxy_pass http://backend-server:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

这样前端就不用区分dev和prod环境，统一把请求发到同源路径，由 Nginx 负责分发，可以规避跨域问题。

2.2 与 MyBatis 搭配时的配置细节

后端接 MyBatis 是不少团队的选择，TinyPro 在页面上的分页、筛选、排序参数有一套默认命名，我们必须把它和后端分页插件对齐。TinyPro 的分页请求参数是current（当前页码）和pageSize（每页条数），排序字段是sortField和sortOrder。Spring Boot 中用 PageHelper 做分页时，接收参数可以这样写：

@GetMapping("/list") public Result<PageResult<UserVO>> list( @RequestParam(defaultValue = "1") int current, @RequestParam(defaultValue = "10") int pageSize, @RequestParam(required = false) String sortField, @RequestParam(required = false) String sortOrder) { PageHelper.startPage(current, pageSize); if (StringUtils.hasText(sortField)) { PageHelper.orderBy(sortField + " " + sortOrder); } List<User> users = userMapper.selectList(); PageInfo<User> pageInfo = new PageInfo<>(users); return Result.success(PageResult.of(pageInfo)); }

这里有个小坑：PageHelper 的分页只对紧接着的一条查询生效，所以排序条件要在selectList之前设置好。TinyPro 前端表格排序触发时会传sortField，后端 SQL 注入风险要注意，最好搞一个字段白名单，不要让前端直接传列名拼 SQL。

返回结构也很关键。TinyPro 默认要求后端返回结构是：

{ "code": 0, "data": { ... }, "message": "success" }

可以把后端统一封装成Result<T>。注意，code=0表示业务成功，非零是业务错误码。这和很多后端项目用的200/500直接状态码逻辑不同，刚开始容易踩坑。我的做法是写一个@RestControllerAdvice，把 HTTP 状态码和业务状态码统一转换，这样前端只认code，不依赖 HTTP header。

2.3 第三方接口与监控端点的组织思路

有朋友问过“Spring Boot 对外提供的接口（给第三方）应该放哪里？是单独的服务还是放在对应服务里？”。这个问题没有标准答案，但我可以分享一个实际使用 TinyPro 管理这种接口的模式。

如果对外接口量不大，且业务逻辑与后台管理领域模型一致，可以直接放在同一个 Spring Boot 服务中，用独立路径前缀区分，比如/open/**作为开放接口，/api/**作为后台接口。开放接口做签名校验和独立限流，TinyPro 里的菜单可以只挂后台接口，不暴露开放接口。如果对外接口量很大，或者需要单独升级、扩容，那就拆成独立服务，引入 API 网关统一鉴权，再在 TinyPro 里加一个“开放平台”页面展示接口调用量和错误次数。

监控端点是另一件让后端头疼的事。Spring Boot Admin 是一个非常成熟的监控组件，TinyPro 可以嵌入一个页面，把http://admin-server:9090放在 iframe 里，或者在后端把 Spring Boot Actuator 的指标通过接口暴露出来，TinyPro 用图表组件展示。v1.4.0 里自带了几个图表页面，配合监控数据非常顺手。我在生产环境就是这么干的：/actuator/health做存活探针，/actuator/metrics收集 JVM 和 HTTP 调用指标，前端用 TinyPro 的仪表盘页面展示 CPU、内存、接口耗时趋势。

3. 移动端适配的实操要点：卡片列表和布局响应式

3.1 移动端适配的基本策略

TinyPro v1.4.0 的移动端适配不是简单套用媒体查询，而是通过布局容器动态调整。它把侧边栏菜单拆成了两部分：宽度小于768px时，侧边栏隐藏，顶部出现汉堡按钮，点击后从左侧滑出抽屉。这个交互模式符合移动端用户的使用习惯，而且抽屉里菜单层级最多三级，再多就会被折叠。

正文区域的栅格系统也做了响应式。桌面端内容区有24栏，平板端压缩为12栏，手机端直接变成单列。我自己调页面时总结了一条经验：不要把栅格只用在整页布局，也用在卡片内部。比如一个业务数据卡片，桌面端字段可以横排显示，手机端则自动改为竖排，这样阅读和操作都不费劲。

3.2 卡片列表：信息密度与手势操作

这次新增的卡片列表是我最喜欢的部分。传统表格在手机上有两个硬伤：横向滚动难，误触率高。TinyPro 的做法是在移动端把表格的行数据渲染成卡片。卡片顶部放主标题，中间放关键字段，底部放操作按钮。字段过多时，卡片不会一股脑全展示，而是默认显示四到五个核心字段，多余内容点击展开。

我实际用下来，卡片设计有几个细节决定了体验：

• 操作按钮必须是图标加文字，纯图标在移动端辨识度太低。
• 卡片左右滑动手势触发操作，比长按弹出操作菜单更直观。比如左滑是“通过”，右滑是“驳回”。
• 卡片间距控制在 12px 左右，太小显得拥挤，太大影响信息密度。
• 卡片首屏高度内，至少可以完整显示两到三张卡片，否则用户会觉得内容太少。

我给团队定的规范是：卡片主标题用 16px 字体加粗，次要字段用 13px 常规颜色，操作按钮至少 44x44px 的点击区域。TinyPro 内置了这套样式，但自定义页面时依然要注意。

3.3 列表性能优化和下拉刷新

移动端列表最容易出现的坑是滚动卡顿。TinyPro 虽然提供了卡片列表组件，但如果后端一次返回一千条数据，照样卡成幻灯片。我通常会在请求参数里加一个pageSize=20，并配合分页加载；当列表滚动到底部时自动请求下一页。如果业务场景非要展示大量数据，那就需要虚拟滚动，TinyPro 的列表组件底层其实已经支持了，只需要开启virtual属性。

下拉刷新是移动端后台的刚需。TinyPro 可以设置页面级的pullRefresh属性，刷新时发出onRefresh事件。我自己在做自定义列表时，用的是浏览器原生touch事件 + 数据请求封装，关键点是刷新过程中要锁定页面滚动，防止用户下拉一半时列表上下窜动。经验是：下拉刷新的阈值设为 70px 左右，超过后松手才触发刷新，这样不会和滚动浏览冲突。

4. 高级表单页面的设计思路与实现细节

4.1 高级表单包含哪些能力

“高级表单”不是指一个表单里字段多，而是指字段之间有联动、有动态校验、有分步提交、有草稿保存。普通的表单只需要label + input + submit，高级表单往往出现在复杂业务场景里，比如创建订单、配置审批流、编辑多语种商品信息等。

TinyPro v1.4.0 新增了高级表单页面模板，包含基本信息区、动态列表区、步骤条和审核结果区。模板里把动态增减行、级联选择、依赖项校验、时间范围校验都做成了可配置的 schema。前端可以根据后端返回的配置动态渲染表单，业务字段发生变化时，后端改一下 JSON 配置就能发布，前端不用反复发版。

4.2 动态校验与联动逻辑

联动逻辑是最容易写出一堆 if-else 的地方。比如一个商品表单里，“是否开启促销”控制“促销价”“促销时间”的显示；用户选择“电子券”后，需要填写券码；选择“实物商品”后，需要填写库存和物流方式。如果全写在组件内部，后期维护成本非常高。

我比较推荐用 schema 驱动的表单方案。TinyPro 的表单组件配合 JSON schema 结构，字段的visible与required都支持表达式，示例如下：

{ "type": "object", "properties": { "saleType": { "type": "string", "enum": ["normal", "promotion", "coupon"] }, "promotionPrice": { "type": "number", "visibleWhen": "saleType == 'promotion'", "requiredWhen": "saleType == 'promotion'" }, "couponCode": { "type": "string", "visibleWhen": "saleType == 'coupon'" } } }

把这个 JSON 抛给前端渲染，字段之间的显隐关系通过表达式解析，而不是散落在各组件事件里。这样做的好处是，当字段规则需要调整时，后端只需要改配置，所有客户端和移动端页面同步生效。要注意的是，规则表达式越简单越好，不要搞过于复杂的嵌套，否则调试时很痛苦。

4.3 表单分步与复杂交互

分步表单适合流程长、字段多的场景。TinyPro 的高阶表单模板把创建流程拆成了“基础信息、业务信息、确认提交”三步。每步之间可以通过next()/prev()切换，但有一个关键点：切换步骤时不能丢失已填写的数据。TinyPro 会把每一步的数据保存在一个全局 store 中，最终提交时再把所有步骤的数据合并成一个对象发给后端。

我在项目里踩过最深的坑是步骤表单的校验时机。如果只校验当前步骤，用户点击下一步，最后一步提交时前面数据已变化，容易产生脏数据。我的做法是在最后提交前，把所有步骤的数据统一跑一次完整校验，发现错误后自动跳转到对应步骤。这个逻辑听起来简单，但实现对表单状态的管理要求很高。TinyPro 在这个版本里已经内置了“提交前整体校验”的钩子，省了很多麻烦。

另一个容易遗漏的是草稿保存。用户在移动端填写长表单，可能填到一半接电话、切后台，再回来时数据丢失会很崩溃。高级表单页面应该具备自动草稿能力：表单值变化后节流地保存到localStorage或后端草稿接口。TinyPro 模板里的草稿保存默认 3 秒做一次防抖，恢复草稿时把数据重新填入表单，这个机制强烈建议保留。

5. 常见问题与排查经验实录

5.1 Spring Boot 版本兼容问题：2.3.x/2.6.x/3.x 的差异

Spring Boot 升级到 3.x 后，最明显的区别是javax.*包改成了jakarta.*。如果你的后端服务还在 2.3 或 2.6 上，依赖注入、事务管理、Servlet API 的包路径都会不一样。TinyPro 前端本身不关心这个差异，但你在对接时要注意：不要在后端代码里直接依赖旧版本的javax.validation，Spring Boot 3.x 需要jakarta.validation。还有，spring.factories自动配置机制废弃，改成了AutoConfiguration.imports。

对前端来说，真正要注意的是接口返回数据结构的一致性。我见过不少项目，Spring Boot 版本一升级，某些统一异常处理器的包名就变了，导致返回结构偶尔会多一层嵌套或者少一个字段。解决办法是写接口契约测试：用 Spring Boot 的@SpringBootTest和MockMvc把关键接口的返回 JSON 结构写成断言，升级版本后跑一遍，确保前端看到的格式没变。

5.2 移动端适配的布局踩坑：安全区与键盘遮挡

移动端开发最烦的是“刘海屏”和“iPhone 底部小黑条”。TinyPro 的布局组件已经加了safe-area-inset-bottom，但如果你用自定义 fixed 的底部操作栏，就得自己处理：

.bottom-bar { position: fixed; bottom: 0; padding-bottom: constant(safe-area-inset-bottom); padding-bottom: env(safe-area-inset-bottom); }

另外，移动端页面输入框聚焦时，iOS 键盘会把fixed定位的底部按钮顶上去，导致按钮遮住输入框。我建议所有移动端表单页面，不使用fixed底部按钮，而是把按钮放在普通文档流中，页面可以滚动到提交按钮的位置。TinyPro 高级表单模板里默认采用文档流式布局按钮，这个细节很加分。

还有一个常见坑是100vh在移动端浏览器里不等于可视区域高度。页面高度包含浏览器地址栏，用100vh会导致底部被截断。改用100dvh或者用window.visualViewport.height动态计算。TinyPro 的布局容器已经做了兼容，但自定义弹层的建议不要直接用height: 100vh。

5.3 表格与卡片列表切换时的性能优化

在桌面端和移动端用同一份数据渲染不同的组件（表格 vs 卡片），需要注意别出现“切换断流”或重复渲染。TinyPro 的做法是在路由层面根据屏幕宽度切换组件，但如果你在一个页面里同时保留两个组件实例，只在断点变化时显示或隐藏，实际上是两个列表都在请求数据，浪费资源。

我的经验是只用一份数据源，配合 CSS 或动态组件切换。组件内部对data的引用是同一个数组，这样切换时不会重新加载数据。真正要注意的是事件绑定：表格行的点击和卡片列表的点击，事件参数不完全一样，最好把点击元素绑定到同一个业务 ID 上，而不是依赖行索引。TinyPro 的列表数据模型在表格和卡片之间是共享的，这一点做得很聪明。

我还遇到过切换后滚动位置丢失的问题。桌面端表格可能有滚动条，手机端卡片列表是页面滚动，两者的滚动容器不同。如果你在移动端点开卡片详情，返回列表时希望回到原位置，需要记录scrollTop。最简单的方案是列表页使用keep-alive缓存，TinyPro 的路由配置里可以给列表页开启缓存，亲测有效。

6. 一些实际使用的补充心得

升级到 v1.4.0 之后，我发现它不只是功能变多了，更关键的是把很多“默认行为”改得更贴近真实业务。比如权限路由从原来单纯的菜单显隐，变成了按钮级别控制，后端返回的权限点可以精确到一个“导出”按钮能不能点。配合 Spring Boot 的 Shiro 或 Spring Security，前后端的权限模型能对齐，这在以前是要额外开发的。

还有一个细节是卡片列表里新增的“批量操作”模式。手机端长按卡片进入多选状态，底部浮出全选、删除、审核按钮。这种交互对移动端管理后台非常有用，比传统 checkbox 列表更顺手。如果你发版后团队成员反馈“运营在手机上处理工单效率提升明显”，那多半就是批量操作这个功能在起作用。

如果要用一句话总结我的升级体验，那就是：TinyPro v1.4.0 把前端模板从“展示层”推进到了“业务层”。它对 Spring Boot 的支持简化了后端联调，移动端适配让审批、查询、订单处理在手机上真正可用，高级表单和卡片列表覆盖了复杂业务最常见的两个场景。建议你现在就拉一个新分支，把小项目数据导进去试试。升级时别只改版本号，先走通登录流程和列表接口，再逐个切换新页面，这样能少踩很多坑。