研发开发规范 · 其他建议规范

本篇学习指南

读完你能

保持仓库整洁（该忽略的忽略、该清理的清理）
了解一个版本从开发到现场部署的完整流程
知道前后端怎么高效协同（接口先行、版本对齐）

阅读时长

约 7 分钟 · 进阶内容，了解即可

前置知识

先通读 01~07

接着读

09-发版与现场验证

概念入门

理解工程规范

仓库卫生: 保持代码仓库整洁，就像保持工位整洁。不该入库的文件（日志、IDE 配置、构建产物）要通过 .gitignore 排除。
SOP Standard Operating Procedure: 标准操作流程。把重复性工作固定为标准步骤，减少遗漏和出错。
.gitignore: 告诉 Git「这些文件不要跟踪」的配置文件。就像告诉保洁阿姨「这个抽屉不用打扫」。

仓库就像你的工位 —— 保持整洁，别人才能快速找到东西

应该入库

源代码

配置文件

SQL 脚本

文档

不该入库

日志文件

IDE 配置

编译产物

.DS_Store

其他建议规范

5.1 仓库卫生

目录合并：

docs/（当前仅含 superpowers，疑似误建）应合并入 doc/。
规范类文档统一归 doc/规则/，业务文档按模块分子目录。

.gitignore 补全（当前缺失以下条目）：

GITIGNORE

# JVM 崩溃日志
hs_err_pid*.log
replay_pid*.log

# 运行日志
logs/
*.log
log.bin
spy.log

# 系统/IDE
.DS_Store
*.iml
.idea/

# 构建产物
target/

已入库文件清理（需执行）：

BASH

# 从 git 移除但保留本地文件（-r --cached）
git rm --cached hs_err_pid12168.log hs_err_pid51356.log hs_err_pid55536.log hs_err_pid58404.log hs_err_pid9340.log
git rm --cached replay_pid*.log spy.log log.bin
git rm --cached .DS_Store
# 之后再 commit

该入库的文件

*.java / *.vue / *.js — 源代码
*.xml / *.sql — 配置、数据库脚本
*.md / *.html — 文档
pom.xml / package.json — 依赖声明

原则：人手写的、需要团队共享的，才入库

不该入库的文件

target/ / node_modules/ — 构建产物，可重新生成
*.log / hs_err_pid* — 运行日志、崩溃日志
.idea/ / *.iml — IDE 个人配置
.DS_Store — macOS 系统文件

原则：机器生成的、个人环境的，一律 .gitignore

为什么构建产物不能入库？① 它们能从源码重新生成，入库是冗余；② 它们体积大、变动频繁，会让仓库膨胀、拉取变慢；③ 不同人本地构建的产物可能不同，造成无意义的冲突。只入库「源」，产物由各人本地构建。

5.2 文档规范

新文档归位：规范类 → doc/规则/；业务设计类 → doc/<模块>/；驱动文档 → doc/驱动设计文档/。
文件头部统一信息块：

```markdown

# <标题>

> 作者：xxx　日期：YYYY-MM-DD　版本：v1.0

```

空文件清理：doc/待优化.md（当前 0 字节）应填充内容或删除。

5.3 发布流程 SOP

版本发版的完整动作按 09·发版检查单逐阶段勾选执行，主干流程如下：

版本开发完成
release/x.x.x 冻结（禁止合入新 feature，仅允许 hotfix）

SQL 定稿 + 回归测试通过
CHANGELOG 登记完整、幂等抽查通过；sql/release/<版本>/ 冻结复制为 sql/tag/<版本>/

打 tag vX.Y.Z
annotated tag，带变更摘要；tag 号 = 安装包版本号

出集成安装包 → 现场部署
安装包附带 sql/tag/<版本>/ SQL，现场按序执行并登记 CHANGELOG

现场发现问题
从 release/x.Y.Z 分支头拉 hotfix/x.Y.Z/<问题>（基线 = 现场已验证状态）

修复 → 现场验证 → 回流 + 清理
只改代码不改库；验证记录落 doc/branch/ 后回流 release/x.Y.Z + 下个开发中 release，然后删除 hotfix 分支

5.4 前后端协同

接口先行：后端先定义 API（路径、入参 DTO、出参 VO），前端据此 mock 开发。
scope 对齐：前后端在 commit、分支、模块命名上共用同一套 scope（见 2.5）。
分支命名同源：前端工程的分支同样遵循 release/、feature/、hotfix/、custom/、dev/ 前缀规范。
版本号联动：前后端版本号在发布时对齐（如后端 v2.1.1 对应前端 v2.1.1），便于现场配对部署。

新手常见问题

仓库卫生、发布流程、协同方面的常见困惑

我不小心把 target/ 构建产物提交进去了，怎么清理？

构建产物不该进仓库——先在 .gitignore 里加上 target/、node_modules/、*.log 等，然后用 git rm --cached -r target/ 从版本控制移除（文件还在本地，只是不再跟踪），再提交这次清理。已入库的文件即使加进 .gitignore 也不会自动忽略，必须 rm --cached。

前端和后端版本号为什么要对齐？各干各的不行吗？

因为现场部署是前后端配对的——后端 v2.1.1 的安装包对应前端 v2.1.1。如果版本错位（后端 2.1.1 配前端 2.1.0），接口可能对不上、功能可能异常。版本号联动让现场运维能一眼确认「这俩是一套的」，避免装错组合。

「接口先行」具体怎么做？后端还没写完前端怎么开发？

后端先定义接口契约（路径、入参 DTO、出参 VO），用 Swagger 注解写清楚。前端拿到接口定义后，据此 mock 数据开发页面，不用等后端实现完成。后端实现好后联调替换 mock 即可。这样前后端能并行推进，而不是前端干等后端。