研发团队协作规范：前后端约定、发布与回滚

团队规范的目标不是增加流程，而是减少重复沟通，让产品、前端、后端、测试和运维对交付边界有一致理解。具体项目可以在本文基础上补充目录结构、组件库、环境地址、负责人和审批要求。

职责与交付边界

需求进入开发前，应明确以下内容：

• 产品目标、核心流程和验收条件。
• 前后端接口、错误状态和空数据行为。
• 测试范围、回归范围和上线检查项。
• 数据变更、兼容窗口以及回滚方式。

职责可以交叉，但每个关键结果都应有明确负责人，避免问题出现后才确认由谁处理。

后端接口约定

接口结构应保持稳定，避免同一个字段在不同状态下出现多种类型。

1
2
3
4
5

{
  "code": 0,
  "message": "ok",
  "data": {}
}

错误信息要同时服务用户与开发排查。面向用户的文案应清楚，堆栈、内部路径和敏感配置只进入日志或受控调试字段。

分页接口应统一页码起点、每页数量和总数表达。例如约定 page 从 1 开始：

1
2
3
4
5
6

{
  "page": 1,
  "pageSize": 20,
  "total": 128,
  "items": []
}

字段名需要表达业务含义。同一概念不要同时出现 userId、uid、memberId，除非它们确实代表不同对象。

前端开发约定

组件应按照业务意图命名，并保持单一主要职责。组件难以阅读时，优先拆出明确的小组件或组合函数，而不是继续增加配置层级。

状态优先放在离使用位置最近的地方，只有跨页面共享或需要持久化时才提升为全局状态。

样式优先复用组件库和设计变量。列表渲染需要稳定标识时使用业务 id，只有列表不会重排、插入或删除时才考虑使用索引。

提交前至少检查：

• 页面是否覆盖加载、空数据、错误和禁用状态。
• 文案是否能被真实用户理解。
• 移动端和桌面端是否都能正常阅读。
• 请求失败、登录失效和重复提交是否有处理。
• 新增逻辑是否可以用更直接的数据结构表达。

发布前

• 确认需求范围、变更清单和验收结果。
• 确认环境变量和配置项已经准备。
• 确认数据库、缓存和第三方服务的兼容方案。
• 确认关键页面、接口、定时任务和数据指标的检查方式。
• 提前准备回滚版本、回滚命令和数据兼容方案。

发布中

发布过程应保留发布时间、版本号、提交记录、执行人和异常情况。涉及多个服务时，需要明确发布顺序和新旧版本兼容窗口。

数据库变更应优先采用向后兼容方式：先增加新结构并兼容读写，再切换业务，最后清理旧结构。不要让应用发布与不可逆数据修改形成单点风险。

发布后

• 检查登录、首页和核心业务流程。
• 检查接口错误率、日志、队列和告警。
• 检查静态资源、上传文件和第三方回调。
• 检查定时任务、缓存和数据同步状态。
• 记录异常、处理结果和需要继续观察的指标。

回滚

回滚方案应在发布前完成。至少明确：

1. 回滚到哪个应用版本。
2. 哪些配置需要恢复。
3. 数据结构是否向后兼容。
4. 回滚后如何验证服务恢复。
5. 哪些新数据需要补偿或重新处理。

如果数据库变更不可逆，单纯回滚代码并不能恢复系统。此时应准备数据备份、补偿脚本或双写过渡方案。

团队持续改进

规范应从真实故障和协作成本中持续更新。每次严重问题复盘后，把可复用的检查项加入开发、测试或发布清单，而不是只记录一次性的处理过程。