企业官网建设流程全解析

如果你维护过一个持续迭代的业务系统，一定对版本号不陌生。29.7 这个数字本身没有任何含义，但围绕它发生的数据库变更、接口调整、前端联调、线上告警和回滚决策，才是真正值得记录的东西。大多数团队的问题不在于代码写得差，而在于一次迭代结束后，所有经验都随记忆流失了。

这篇文章用“雾山实录29.7”这个演示项目，完整拆解一次从需求拆解到上线排错的迭代过程。它不是一篇抽象的项目管理文章，而是会落到 SQL、Java、Vue 和发布脚本上的实战记录。读完你至少能带走两样东西：一套可以直接复用的迭代复盘框架，以及几个在真实项目中反复出现的坑和对应解法。

1. 雾山实录29.7 到底在记录什么

先解释一下标题的构成。“雾山”是演示项目的代号，“实录”表示这是一次开发过程的完整记录，“29.7”是项目从 29.6 迭代上来的小版本号。在语义化版本规范里，小版本号通常意味着新增功能、接口调整或体验优化，不涉及破坏性的整体重构。所以这次迭代的定位是：在既有订单系统上做一轮局部优化。

这轮优化的背景很常见：29.6 版本里，订单列表页每次进入都会全量加载最近三个月的订单数据，用户多的时候接口响应时间接近三秒。产品经理反馈“页面转圈太久”，技术侧的结论是缺了分页、缺了状态筛选、也缺了取消订单后的状态闭环。29.7 的目标因此收敛为三个点：

1. 订单列表接口支持分页和状态筛选。
2. 新增取消订单接口，并保证幂等。
3. 前端页面配合改造，展示分页器和筛选条件。

这个版本真正值得记录的难点，不在功能本身，而在几个隐藏的地方：数据库表结构变更如何平滑执行、接口设计如何避免前后端字段歧义、线上慢 SQL 为什么加了索引还是不生效、以及发布之后如何快速回滚。这些才是项目迭代中最消耗精力的部分。

要提醒的是，“雾山实录29.7”是一个演示性质的版本号，不代表某个真实开源项目。代码示例会以一套常见的技术栈实现：Spring Boot + MyBatis-Plus + MySQL + Vue 3。你在实际项目中应替换成团队自己的包名、类名和规范，但核心流程是完全共通的。

2. 环境准备与前置条件

动手之前先把环境理清楚。雾山项目采用前后端分离结构，后端是 Spring Boot，前端是 Vue 3，数据库使用 MySQL。以下版本要求以演示项目为准，实际开发请以团队统一使用的版本为基础，不建议为了跑本文示例单独升级项目。

建议环境清单：

后端工程的pom.xml核心依赖如下，文件路径为pom.xml：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-spring-boot3-starter</artifactId> <version>3.5.7</version> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>

注意：如果你使用的是 Spring Boot 2.x，需要把mybatis-plus-spring-boot3-starter换成mybatis-plus-boot-starter，否则会出现自动装配类找不到的问题。

数据库连接配置放在src/main/resources/application.yml中：

server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/wushan_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0

这里有一个值得注意的细节：map-underscore-to-camel-case设置为 true，可以把数据库中的create_time自动映射到 Java 字段createTime，避免在代码里手写大量@TableField注解。logic-delete-field则开启了逻辑删除，业务系统里不要直接物理删除订单，否则后续对账和审计会非常麻烦。

环境准备完成后，先确认 MySQL 中已存在wushan_db数据库，再进入下一步。如果表结构还没建，建议先执行下文第 4 章的建表 SQL。

3. 需求拆解与接口设计

29.7 的需求拆解可以分成三类：数据库变更、后端接口、前端页面。数据库变更必须先做评估，因为表结构改动会影响已经上线的 29.6 版本。

29.7 的数据库需求有两个：

1. order_info表新增cancel_reason字段，用于记录取消原因。
2. 为status和create_time建立联合索引，优化列表筛选查询。

后端接口需求有两个：

1. 改造订单分页查询接口。
2. 新增取消订单接口。

接口设计要先定契约，再写代码。这里有一个容易踩的坑：前后端字段命名不一致。比如后端习惯用orderId，前端某些老页面却用orderNo；后端返回createTime，前端却以为字段名是create_date。29.7 在接口设计阶段就把字段定死，减少联调阶段的返工。

接口约定如下：

分页接口的参数含义要明确：pageNo从 1 开始，pageSize默认 20，最大不超过 100。status是可选参数，不传时查询全部状态。

取消接口的语义也要提前定义：只有PAID状态的订单可以取消，SHIPPED和COMPLETED状态不能取消。取消成功后，订单状态变成CANCELLED，并且写入取消原因。如果订单已经处于CANCELLED，再次调用接口时不能报错，而是直接返回当前状态，也就是要保证幂等。

这样设计的好处是：接口职责单一，前端容易理解；服务端可以做状态校验，避免脏数据；幂等逻辑让调用方可以放心重试，不需要额外引入分布式锁就能处理大部分重复请求场景。

4. 数据库变更与后端实现

4.1 数据库变更脚本

数据库变更脚本是所有步骤里最需要谨慎的地方。生产环境执行前，一定要先在测试库验证，并且备份原表。下面是 29.7 的变更脚本，文件路径为sql/upgrade_29.7.sql：

-- 1. 新增取消原因字段 ALTER TABLE `order_info` ADD COLUMN `cancel_reason` VARCHAR(255) NULL COMMENT '取消原因' AFTER `status`; -- 2. 为订单状态和创建时间创建联合索引 ALTER TABLE `order_info` ADD INDEX `idx_status_create_time` (`status`, `create_time`);

为什么要把status放在联合索引的左侧？因为查询条件先按状态筛选，再按时间排序。遵循最左前缀原则，status放前面才能让索引同时服务筛选和排序。如果你的查询还有user_id条件，需要结合真实业务重新评估字段顺序，不能照搬。

如果表的数据量已经很大，建议不要直接执行原生ALTER TABLE，而是使用在线变更工具，并安排在业务低峰期执行。MySQL 8.x 支持ALGORITHM=INPLACE，但具体是否触发锁表，取决于表结构和版本，务必提前在测试环境验证。

4.2 订单实体与 Mapper

实体类放在src/main/java/com/wushan/order/entity/OrderInfo.java：

package com.wushan.order.entity; import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import lombok.Data; import java.math.BigDecimal; import java.time.LocalDateTime; @Data @TableName("order_info") public class OrderInfo { @TableId(type = IdType.AUTO) private Long id; private String orderNo; private Long userId; private BigDecimal amount; /** * 订单状态：PAID 已支付，SHIPPED 已发货， * COMPLETED 已完成，CANCELLED 已取消 */ private String status; private String cancelReason; private LocalDateTime createTime; private LocalDateTime updateTime; private Integer deleted; }

Mapper 接口放在src/main/java/com/wushan/order/mapper/OrderInfoMapper.java：

package com.wushan.order.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.wushan.order.entity.OrderInfo; public interface OrderInfoMapper extends BaseMapper<OrderInfo> { }

在 MyBatis-Plus 中，继承BaseMapper<T>就已经提供了单表分页、条件查询、更新、删除等基础方法。对于 29.7 这种简单的需求，不需要手写 XML SQL，这样可以减少维护成本。如果后续业务复杂到需要多表关联，再考虑自定义 SQL。

4.3 Service 层实现

Service 层要承载核心业务逻辑：分页查询和取消订单。文件路径为src/main/java/com/wushan/order/service/OrderInfoService.java：

package com.wushan.order.service; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.wushan.order.entity.OrderInfo; import com.wushan.order.mapper.OrderInfoMapper; import org.springframework.stereotype.Service; @Service public class OrderInfoService { private final OrderInfoMapper orderInfoMapper; public OrderInfoService(OrderInfoMapper orderInfoMapper) { this.orderInfoMapper = orderInfoMapper; } public Page<OrderInfo> pageOrders(long pageNo, long pageSize, String status) { LambdaQueryWrapper<OrderInfo> wrapper = new LambdaQueryWrapper<>(); wrapper.eq(OrderInfo::getDeleted, 0); if (status != null && !status.isEmpty()) { wrapper.eq(OrderInfo::getStatus, status); } wrapper.orderByDesc(OrderInfo::getCreateTime); return orderInfoMapper.selectPage(new Page<>(pageNo, pageSize), wrapper); } public OrderInfo cancelOrder(Long orderId, String cancelReason) { OrderInfo order = orderInfoMapper.selectById(orderId); if (order == null) { throw new IllegalArgumentException("订单不存在"); } // 幂等处理：已经是取消状态，直接返回 if ("CANCELLED".equals(order.getStatus())) { return order; } // 状态校验：仅允许取消已支付订单 if (!"PAID".equals(order.getStatus())) { throw new IllegalStateException("当前订单状态不允许取消"); } OrderInfo update = new OrderInfo(); update.setId(orderId); update.setStatus("CANCELLED"); update.setCancelReason(cancelReason); orderInfoMapper.updateById(update); return orderInfoMapper.selectById(orderId); } }

这段代码有几个值得讲的点。

第一，分页查询用了LambdaQueryWrapper，参数通过 lambda 引用字段名，比字符串写法更安全。编译期就能发现字段名拼写错误，而不是等运行时才报错。

第二，取消订单时先查一次数据库，判断状态，再更新。这里有并发问题：两个请求同时查到订单是PAID，都执行更新，最终结果仍是CANCELLED，业务上不会出错。但如果后续要记录取消操作人、取消时间，或者要发送通知，就必须引入乐观锁或分布式锁做并发控制。

第三，幂等处理放在状态判断里，而不是依赖前端按钮防抖。后端接口必须自己扛住重复请求，这是接口设计的基本要求。

4.4 Controller 层实现

Controller 层放在src/main/java/com/wushan/order/controller/OrderInfoController.java：

package com.wushan.order.controller; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.wushan.order.entity.OrderInfo; import com.wushan.order.service.OrderInfoService; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/orders") public class OrderInfoController { private final OrderInfoService orderInfoService; public OrderInfoController(OrderInfoService orderInfoService) { this.orderInfoService = orderInfoService; } @GetMapping public Result<Page<OrderInfo>> pageOrders( @RequestParam(defaultValue = "1") long pageNo, @RequestParam(defaultValue = "20") long pageSize, @RequestParam(required = false) String status) { return Result.ok(orderInfoService.pageOrders(pageNo, pageSize, status)); } @PostMapping("/{orderId}/cancel") public Result<OrderInfo> cancelOrder(@PathVariable Long orderId, @RequestParam String cancelReason) { return Result.ok(orderInfoService.cancelOrder(orderId, cancelReason)); } }

这里的Result是统一返回体，实际项目中一般会封装为code、message、data三个字段。Controller 层只做参数接收和结果包装，不要写业务逻辑。这样后续做参数校验、统一异常处理时，改动可以集中在同一层。

5. 前端联调与页面改造

后端的接口定义清楚后，前端开发可以并行开工。29.7 前端部分的核心是订单列表页，技术栈为 Vue 3 + Element Plus。

订单列表组件改造成三部分：状态筛选、分页表格、分页器。代码文件为src/views/order/OrderList.vue：

<template> <div> <el-form :inline="true"> <el-form-item label="订单状态"> <el-select v-model="queryParams.status" placeholder="全部状态" clearable> <el-option label="已支付" value="PAID" /> <el-option label="已发货" value="SHIPPED" /> <el-option label="已完成" value="COMPLETED" /> <el-option label="已取消" value="CANCELLED" /> </el-select> </el-form-item> <el-form-item> <el-button type="primary" @click="handleSearch">查询</el-button> </el-form-item> </el-form> <el-table :data="orderList" border> <el-table-column prop="orderNo" label="订单号" width="200" /> <el-table-column prop="amount" label="金额" width="120" /> <el-table-column prop="status" label="状态" width="120" /> <el-table-column prop="createTime" label="创建时间" width="180" /> <el-table-column label="操作"> <template #default="{ row }"> <el-button v-if="row.status === 'PAID'" type="danger" link @click="handleCancel(row)" > 取消订单 </el-button> </template> </el-table-column> </el-table> <el-pagination v-model:current-page="queryParams.pageNo" v-model:page-size="queryParams.pageSize" :total="total" :page-sizes="[10, 20, 50, 100]" layout="total, sizes, prev, pager, next, jumper" @size-change="handleSearch" @current-change="handleSearch" /> </div> </template> <script setup> import { reactive, ref, onMounted } from 'vue' import { getOrderPage, cancelOrder } from '@/api/order' import { ElMessage, ElMessageBox } from 'element-plus' const queryParams = reactive({ pageNo: 1, pageSize: 20, status: '' }) const orderList = ref([]) const total = ref(0) async function fetchOrderList() { const { data } = await getOrderPage(queryParams) orderList.value = data.records total.value = Number(data.total) } function handleSearch() { queryParams.pageNo = 1 fetchOrderList() } async function handleCancel(row) { await ElMessageBox.confirm('确认取消该订单吗？', '提示', { type: 'warning' }) await cancelOrder(row.id, '用户主动取消') ElMessage.success('订单已取消') fetchOrderList() } onMounted(fetchOrderList) </script>

对应的 API 封装在src/api/order.js：

import request from '@/utils/request' export function getOrderPage(params) { return request({ url: '/api/orders', method: 'get', params }) } export function cancelOrder(orderId, cancelReason) { return request({ url: `/api/orders/${orderId}/cancel`, method: 'post', params: { cancelReason } }) }

联调阶段最常遇到的三个问题，这里提前说明。

第一，字段名大小写。后端返回createTime，前端如果写成create_time，页面上永远显示空白。遇到这种问题，先打开浏览器 Network 面板看原始响应，再检查前端取值字段。

第二，时间格式。后端LocalDateTime默认序列化结果是2025-01-01T10:30:00，前端如果直接展示会带一个T，体验很差。实际项目中一般会在application.yml配置全局时间格式，或使用 Jackson 的@JsonFormat注解统一处理。

第三，空状态。分页查询返回records为空数组时，表格组件会展示内置空状态；但如果后端返回null，某些组件会渲染异常。所以后端分页接口必须保证records是空数组，不能是null。

6. 线上排错实录：慢 SQL、空指针、缓存一致性

29.7 上线后的前两个小时，监控系统连续弹出告警，问题集中在三个方向。这一章是把排错过程记录下来的核心部分，也是很多人觉得“版本实录没意义”但实际上最有价值的部分。

6.1 慢 SQL：加了索引为什么不生效

告警信息显示，订单列表接口的平均响应时间超过了 1500 毫秒。慢查询日志里有一条 SQL：

SELECT * FROM order_info WHERE deleted = 0 AND DATE_FORMAT(create_time, '%Y-%m-%d') >= '2025-01-01' ORDER BY create_time DESC LIMIT 20;

联合索引idx_status_create_time看起来应该覆盖这个查询，但用EXPLAIN查看执行计划时，发现key是NULL，也就是说索引没有生效。

原因很典型：查询条件里对create_time使用了DATE_FORMAT函数，函数包裹字段后，索引无法利用。这不是 PostgreSQL 或者 MySQL 的 Bug，而是数据库优化器的正常工作方式：对索引列做计算时，索引项和查询值无法直接比较。

修复方式是去掉函数包裹，直接用范围查询：

SELECT * FROM order_info WHERE deleted = 0 AND create_time >= '2025-01-01 00:00:00' AND create_time < '2025-01-02 00:00:00' ORDER BY create_time DESC LIMIT 20;

这个问题的教训是：写查询条件时，尽量保持字段独立在比较运算符一侧，不要在索引列上做函数计算或者隐式类型转换。EXPLAIN查看执行计划，应该作为 SQL 上线的固定检查步骤。

6.2 空指针：接口入参不是每次都有

取消订单接口上线后，某次调用直接返回 500，后端日志抛了NullPointerException。定位后发现，代码里对order对象做了判空，但没对cancelReason判空。前端某个老版本页面在用户不输入原因时，会传一个空字符串，但另一个内部系统调用时直接没传这个参数，于是cancelReason为null，后续写入数据库时触发异常。

修复方案有两个层面。第一层，接口入参增加校验：

@PostMapping("/{orderId}/cancel") public Result<OrderInfo> cancelOrder(@PathVariable Long orderId, @RequestParam(required = false) String cancelReason) { if (cancelReason == null || cancelReason.trim().isEmpty()) { cancelReason = "用户未填写取消原因"; } return Result.ok(orderInfoService.cancelOrder(orderId, cancelReason)); }

第二层，数据库字段继续允许NULL，但业务上必须保证写入时至少有默认值。实际项目里可以使用校验框架，例如@NotNull、@NotBlank，但要注意区分必填参数和可选参数，不能一股脑全加。

6.3 缓存一致性：删除缓存比更新缓存更安全

订单查询带上了缓存以后，又出现了一个新问题：用户取消订单后，列表页仍然显示“已支付”。原因是更新数据库后，缓存里还是旧数据。常见做法有两种：更新缓存和删除缓存。两者都能用，但更新缓存有一个隐患：如果数据库更新成功、缓存更新失败，数据就不一致了。

更稳妥的策略是“先更新数据库，再删除缓存”。下次查询时缓存未命中，从数据库加载最新数据回填。这样即使删除缓存失败，也只是多一次数据库查询，不会返回脏数据。实际项目中还可以给缓存设置过期时间作为兜底。

缓存操作的代码片段如下：

public OrderInfo cancelOrder(Long orderId, String cancelReason) { // 1. 更新数据库 OrderInfo order = doCancelOrder(orderId, cancelReason); // 2. 删除缓存，而非更新缓存 redisTemplate.delete("order:detail:" + orderId); return order; }

这里的doCancelOrder是上面 Service 里的核心逻辑，缓存删除放在事务提交之后。如果你使用了@Transactional，要注意事务提交时机与缓存操作的顺序，避免事务未提交缓存已删除，导致查询把旧数据再次回填到缓存。

7. 发布与回滚：从提交到上线的完整路径

29.7 的发布流程可以总结为四步：测试环境验证、预发环境验证、灰度发布、全量发布。每一步都要有明确的通过标准。

发布前确认单建议包含以下内容：

1. 数据库变更脚本已在测试库执行，且不影响存量数据。
2. 后端接口在测试环境自测通过。
3. 前端页面完成联调，核心操作有自动化用例或手工测试记录。
4. 回滚方案已确认，数据库脚本有对应回滚 SQL。

发布脚本可以简化到一个可以重复执行的样子。文件路径为deploy/deploy_29.7.sh：

#!/bin/bash # 雾山项目 29.7 版本发布脚本 # 用法：./deploy_29.7.sh [test|gray|prod] ENV=$1 echo "开始部署环境: ${ENV}" # 1. 备份当前版本 tar -czvf "backup_$(date +%Y%m%d%H%M%S).tar.gz" wushan-app.jar # 2. 停止旧进程 pkill -f wushan-app.jar || true sleep 3 # 3. 启动新版本 nohup java -jar wushan-app.jar \ --spring.profiles.active=${ENV} \ > app.log 2>&1 & echo "部署完成，请观察启动日志" tail -f app.log

回滚预案要提前写清楚。代码回滚最容易，Git 切回上一个 tag 重新构建即可。数据库回滚要更谨慎，因为ALTER TABLE新增字段可能已经被其他新代码引用，回滚代码后，新增字段暂时保留不会影响旧版本运行。如果必须移除字段，要单独安排低峰期执行，并再次备份。

order_info表的回滚 SQL 如下，仅供紧急回滚使用，实际执行前必须确认没有 29.7 的数据写入逻辑还在运行：

-- 回滚前先备份数据 CREATE TABLE order_info_bak_29_7 AS SELECT * FROM order_info; -- 移除索引与字段 ALTER TABLE `order_info` DROP INDEX `idx_status_create_time`; ALTER TABLE `order_info` DROP COLUMN `cancel_reason`;

这里要特别强调安全底线：生产数据库的任何变更，都必须先在测试环境完整验证；执行变更前必须备份；变更后要能快速回滚。不要让一个没有数据库权限的人直接在生产库执行脚本，权限控制要遵循最小权限原则。

8. 常见问题与排查思路

29.7 版本迭代过程中，有几个问题反复出现，整理成排查表方便后续使用。

排查线上问题时，第一条原则是先看日志，再看指标，最后改代码。日志要包含请求入参、业务关键节点和异常堆栈，避免上线后只能靠猜。如果当时没有在关键节点打印日志，排查效率会非常低。

9. 最佳实践与工程建议

29.7 的版本开发记录到此已经完整。最后把这次迭代中验证过有效的工程习惯总结一下，这些比单个功能点更值得应用到下一个版本。

第一，数据库变更脚本要纳入版本管理。不要只把表结构调整记录在一个共享文档里，而是像代码一样放在 Git 仓库，按版本号命名。这样任何环境都能重复执行，回滚时也能快速找到对应 SQL。

第二，接口设计先定契约，再写实现。Postman 的接口文档也好，Swagger 注解也好，至少要保证字段名、类型、语义在前后端达成一致。一个字段的命名争议，可能消耗比写接口更长的联调时间。

第三，SQL 上线前执行 EXPLAIN。尤其是新建了联合索引的场景，必须确认执行计划真正用到了索引。不要以为建立了索引就万事大吉，函数包裹、隐式类型转换、错误的字段顺序都会让索引失效。

第四，生产变更要有回滚意识。数据库变更尤其要注意备份和回滚脚本。发布流程里可以设置一个固定步骤：没有回滚方案，不允许发布。

第五，版本实录要写“为什么”，不只要写“做了什么”。比如取消订单接口为什么要求幂等，是因为前端按钮可能被重复点击，后端消息重试也可能触发重复请求。把这些决策原因记录下来，下一个接手的人才知道哪些地方不能随意改。

下一步可以继续深入的方向包括：为订单列表接口建立性能基线，用压测工具记录 P95 响应时间；把关键接口的自动化回归用例纳入 CI，避免类似问题在 29.8 重新出现；如果订单量继续增长，还可以思考分库分表方案。结合自己的项目把这次流程跑一遍，会比收藏本文产生更大的价值。