成为全栈·Go 后端篇·重写之前先锁基线：契约、Node 版本与行为清单

成为全栈·Go 后端篇·重写之前先锁基线：契约、Node 版本与行为清单

重写同一套后端，第一步不是创建 Go 项目，而是搞清楚"同一套"究竟指什么。

本文代码快照：Go 后端提交 ceac4e0；API 契约 1.12.0，SHA-256 为 7b252c7ca701b45fdfd2a1e9dc7650085ff36e4ee9644265ad3fb6c485a5e030；Node 对照为 node-backend-v1.0.4，提交 7effc0276ffdf2fbd8183ec2e60d544ed8998bec。

前言：最容易被忽略的，是"重写对象"本身

写第一行业务代码之前，我先花了半天把三样东西固定下来：冻结的 OpenAPI、要对照的 Node 提交、能重复执行的行为验证。当时觉得自己在磨蹭。

如果你已经读过 Node 后端篇，可能会觉得 Go 版的起步很直接：新建工程，选个 Web 框架，连上数据库，把已有接口重新写一遍。

这句话里的"已有接口"，看起来特别明确。可一旦真的动手，我们很快会遇到一些无法靠复制代码回答的问题：契约里 pageSize 默认是 10，Node 的通用分页工具却给了 20；某个响应字段允许 null，某个客户端又把它当成普通字符串；冻结文档写一种状态转移，历史实现却留下另一种行为。此时，Go 应该照着哪一边做？

我在开始 M6 时，先把三个参照物锁下来：冻结的 OpenAPI 契约、要对照的 Node 代码版本，以及可以重复执行的行为验证。这个动作不是文档洁癖，而是给后续每一次"兼容"判断设定基准。基准不清楚，差分测试只能告诉我们"两个结果不同"，却不能告诉我们"哪一个结果应该被保留"。

这篇先把 M6 的重写对象说清楚。后续文章会进入 Go 工程、契约接入和数据库实现；这里不讲 net/http 或 GORM 的用法，而是讲在写第一段业务代码之前，怎样避免把重写变成一次没有边界的产品改版。

一、先分清三种"正确答案"

一个已经运行的系统，至少可能同时存在三套答案：

参照物	它回答什么	M6 中的用途
产品与领域决策	系统应该提供什么行为	判断功能、状态、权限和用户预期
冻结 API 契约	客户端可以依赖什么协议	判断字段、类型、路径、鉴权和响应结构
Node 现有实现	旧系统现在实际怎么运行	发现兼容差异、作为对照实现和迁移来源

理想情况下，这三者完全一致。真实工程里，它们未必同步更新。Node 可能有历史行为，契约可能只表达了结构而没有表达清楚某个边界，产品规则也可能在实现后才进一步收紧。

因此，"复刻 Node"与"遵守契约"不能简单画等号。假设 Node 默认返回 20 条，而契约针对某端点明确规定默认 10 条，Go 若返回 20 条，的确与 Node 当前行为一致，却不符合被冻结的协议。反过来，某个产品语义已经被契约明确收紧，而 Node 还保留旧行为，机械照抄也不是高质量兼容。

M6 的处理方式是：把冻结契约作为对客户端的协议边界，把 Node 作为待比较的真实实现，把产品规则作为解释差异和判断演进方向的依据。任何不一致都先登记，再决定处理，而不是在代码里悄悄选择对自己最方便的一方。

这并不意味着每次都让 Go "修正" Node。跨版本替换要考虑已有客户端实际依赖的行为。如果差异可能造成真实用户行为变化，就必须作为明确的兼容决策记录下来。关键是让决定可以被审阅，而不是把它藏在一个默认值或 if 分支里。

二、我们锁定了哪些基线

M6 开始实现前，基线记录了三个具体对象。

第一，OpenAPI 契约是版本 1.12.0，共 54 个路径、68 个操作。文件的 SHA-256 是：

7b252c7ca701b45fdfd2a1e9dc7650085ff36e4ee9644265ad3fb6c485a5e030

摘要值不是协议本身，但能帮助后来者确认，文章或测试引用的是不是同一份文件。文件内容可以继续演进；一旦变化，摘要自然改变，读者就知道需要重新核对基线。

元数据本身也是基线的一部分。打开生成快照，就能看到它的身份与限流约定（为篇幅省略长描述字段）：

{
  "openapi": "3.1.0",
  "info": {
    "title": "文章系统 API",
    "version": "1.12.0",
    "x-api-version": 1,
    "x-rate-limit": {
      "limit": 60,
      "window": "1m",
      "code": 5001,
      "scope": "per-endpoint",
      "key": "client"
    }
  },
  "servers": [
    { "url": "http://localhost:3000", "description": "本地开发（Node 后端）" },
    { "url": "http://localhost:8080", "description": "本地开发（Go 后端重写）" }
  ]
}

version 与文章里写的 1.12.0 对应，x-rate-limit 说明限流是每个公开端点独立计数、超限返回 429 与业务码 5001，servers 则把 Node 和 Go 两个本地入口都列了出来。这些都不是散文描述，而是可以被程序读取的约束。

第二，Node 对照版本是 node-backend-v1.0.4，提交为：

7effc0276ffdf2fbd8183ec2e60d544ed8998bec

这里要特别区分"目前仓库里最新的 Node 代码"和"本次实验所用的 Node 基线"。如果使用活动工作目录直接跑差分，后来一次无关改动就可能改变结果。固定 tag 和提交，能够说明比较对象是什么。

第三，Go 实现位于独立的 go-backend/ 模块，并通过本地保存的契约 JSON 快照参与校验。快照由唯一 YAML 源文件生成；同步检查确认快照没有过期。这样，Go 服务不必把协议的另一份手工副本当成新事实源。

这三个基线解决的是不同问题：契约决定"客户端协议如何解释"，Node 版本决定"比较对象是哪一版"，快照和提交记录则决定"实验能否复现"。不能用一串版本号替代三者，也不能因为 Git 历史存在，就假定读者知道本次究竟比较了哪个 commit。

三、先列行为清单，再开始重写

只有端点列表是不够的。一个端点的路径和成功 JSON 只是协议的一部分。输入是否允许省略、null 与空字符串有什么区别、重复请求是否幂等、失败时之前写入是否回滚，都会影响真实客户端。

M6 的行为清单把验证问题拆成几类：

• 操作覆盖：每个冻结操作是否都有实现和成功响应检查？
• 输入边界：匿名用户、错误角色、非资源所有者、缺失字段和非法状态分别得到什么结果？
• 状态不变量：点赞关系与计数是否同步？refresh token 重放后，旧令牌家族是否真的失效？
• 失败后的数据状态：通知插入失败时，文章发布是否也回滚？附件元数据写入失败后，共享对象有没有被误删？
• 跨实现差异：同一请求在 Go 与 Node 之间有哪些不同，差异究竟来自随机值、运行时环境，还是产品规则？
• 外部消费者：现有 Web、管理后台、Flutter 和 Taro 请求层是否仍能完成关键流程？

这张清单的价值，在于把"功能做了"变成可观察的问题。例如，仅看到点赞接口返回成功，不能证明点赞计数正确；只有再检查关系表和文章计数，才能验证业务不变量。只看到微信 callback 返回 token，也不能证明首次建号的并发竞争不会创建两个用户。

当然，清单也不等于穷举所有输入组合。M6 的成功测试覆盖 68 个操作，另有逐操作鉴权与输入边界断言；这说明已经覆盖了明确列出的场景，不等于所有可能参数组合都被测试。文章保留这条边界，读者才知道证据能支持多强的结论。

四、差异登记表：不要让"绿色"替你做产品决定

对照 Node 时，M6 记录了已经确认的几类差异。下面的例子能说明为什么我们先判定依据，再调整实现：

场景	冻结契约 / 产品规则	Node 基线现象	Go 的处理与理由
搜索默认条数	端点默认 pageSize=10	通用分页默认 20	遵守端点的冻结默认；记录差异，不改成 20 追求逐字节相同
阅读冷却	滚动 24 小时	按 UTC 日期桶计算	按产品规则实现滚动窗口，并覆盖午夜边界
评论删除	回复关系可以多层	旧实现只处理一层子项	删除整支回复，响应仍遵循既有平面结构
文章删除与 slug	已删除资源不应阻止有效新内容复用	旧路径留下非空 slug	释放冲突标识，并用复用场景验证
发布通知	审核通过产生产品事件	Node 尚未生成同等事件	Go 在状态变更事务中写入，并把实际增量列为差异

这里每一行都不能被简化成"Go 比 Node 更正确"。首先要说明判据来自哪里；接着说明用户或客户端会看到什么；最后通过实际断言证明决定确实生效。评论整支删除等规则若会影响用户已有数据，应当由产品语义和契约关系支持，而不能只因为新实现"写起来顺手"。

一个常见陷阱是把差分测试设成"任何字节不一样就失败"。随机令牌、临时微信用户名、受控时间戳可能需要规范化；但规范化范围如果太宽，测试又会把真正的问题一并吞掉。M6 的做法是明确列出允许变化的字段，其他字段继续精确比较，特别保留状态码、业务码、空值、字段类型、数组顺序和计数。

差异登记表也不是给差异"发许可证"。它的作用是让每项偏差都回答三个问题：差异是什么？依据是什么？通过什么测试证明它被有意接受？没有答案的差异仍然是待解决问题。

五、契约文件不能只看起来像 OpenAPI

契约先行容易被误解为"有 OpenAPI YAML，就可以直接生成 Go 服务"。实际接入时，规范版本、校验器行为、生成器能力、项目里的历史约定都需要验证。

M6 的契约使用 OpenAPI 3.1。实现保存了生成的 JSON 快照，并在验证入口检查快照与 YAML 是否一致。请求进入业务前经过契约 schema 与操作级校验；但校验通过不能代替权限、状态机、数据库约束和事务测试。

一个操作在契约里携带的信息，远不止路径和方法。下面是创建文章操作在 JSON 快照中的原始片段：

"post": {
  "operationId": "createArticle",
  "x-authz": {
    "minRole": "member"
  },
  "tags": [
    "Article"
  ],
  "summary": "创建文章",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ArticleCreate"
        }
      }
    }
  }
}

operationId 是 Go 侧 handler 注册与权限判断的键；x-authz.minRole 声明最低角色；requestBody.required 说明请求体不可省略；$ref 指向共享的 ArticleCreate schema。这四项组合起来才是"创建文章"这个操作的完整协议，而路径字符串本身只表达了很小一部分。

一些契约表达与历史实现之间的冲突，需要局部处理，而不是重写整个文件。例如，nullable 在内存中需要转换成校验器支持的形式；部分 SiteSetting 响应 schema 与全局响应信封约定不完全一致；附件 URI 字段标成绝对地址，而实际接口会返回相对路径。这些情况都登记到验证报告，Go 在校验边界做明确兼容，不把源 YAML 静默改成"更好看"的新协议。

这个经验对前端工程师尤其重要。前端通常把 OpenAPI 当成类型来源；到了后端，我们还要进一步问：验证器究竟执行了什么？空值按什么语义进入领域层？字段是否真的从请求中提交？生成出的类型是否能表达缺失和 null？

"契约是事实源"并不表示契约文本本身永远没有歧义。它表示歧义要在可见的位置处理，有证据支撑，并且不得由单个实现偷偷改变所有消费者所依赖的协议。

六、基线会直接影响实现架构

锁定参照物不是一次性的项目管理动作，它会反过来改变代码结构。

例如，如果输入中的"未提交"和 null 被当作同一种情况，领域层就无法正确实现部分更新。于是 M6 将字段存在性保留在 values.Fields，让业务映射可以区分"保持原值""显式清空"和"赋值为零值"。

如果把 ORM 行直接序列化为响应，就很难保证输出符合契约，也可能暴露不应返回的密码哈希或微信身份字段。因此持久化记录和响应 DTO 分开，响应由代码显式组装。

如果把跨数据库差异当成连接字符串差异，迁移和查询就会散布许多意料之外的方言条件。M6 将方言驱动和版本 SQL 放在平台层，同时用真实 SQLite、PostgreSQL 与 MySQL 验证，而不是假设 ORM 会自动抹平每种行为。

如果只比较成功响应、不检查失败后的数据库状态，刷新令牌重放和通知回滚就可能表面返回正确错误码，实际安全状态却已经被回滚或部分写入。于是交易测试把"返回什么"和"数据库留下什么"一并断言。

这些不是为了先造一个大框架。它们都是在明确协议与行为后，为了保住具体语义而形成的最小结构。后续架构篇会解释为什么 Go 版没有照搬 TypeScript 目录，也没有为了"抽象漂亮"增加一套通用 Repository。

七、复现基线检查：从仓库里的文件开始

读者可以先在仓库根目录完成三项只读检查。命令的目的不是马上运行两个服务，而是确认材料与文章描述的是同一版本：

# 1. 查看冻结契约版本及路径/操作数量
rg -n 'openapi:|info:|paths:' docs/api/openapi.v1.yaml

# 2. 确认 Node 对照 tag 指向的提交
git rev-parse 'node-backend-v1.0.4^{commit}'

# 3. 查看 Go 模块身份及契约快照检查入口
cat go-backend/go.mod
cd go-backend && node scripts/sync-contract.cjs --check

第一条 rg 只定位字段，不负责解析 YAML，也不能可靠地数出 68 个操作；操作总数应看已保存的契约覆盖报告，或使用实际解析工具。第二条命令若本地未获取标签，会明确失败，此时应先根据仓库约定同步代码标签，不能拿另一个相近提交代替。第三条检查确认生成快照没有过期，但不启动服务，也不运行数据库矩阵。

这组命令刻意很短：读者先建立"本文依据在哪里"的定位能力，等到后续契约篇和验证篇再动手跑完整测试。若复制命令时发现当前仓库文件已更新，优先以文章写明的代码快照和对应提交为准，并把新旧差异单独记录。

八、这一篇不证明什么

基线锁定只为后续验证提供边界，它本身不能证明 Go 已经可替换 Node，也不能说明真实用户在切换后毫无感知。它没有覆盖真实微信网络、真实 R2 账号、Linux 容器部署或生产数据迁移。这些验证需要各自的环境与授权。

M6 已有的数据库矩阵在隔离的 SQLite、PostgreSQL 17 和 MySQL 8.4 上执行。Node/Go 差分在隔离测试数据、受控时间和微信替身下完成。迁移使用 Node SQLite 副本和空目标库演练。客户端验证执行的是现有请求/会话代码；这不等于四端所有页面都用真实设备重新走查。

把这些范围在文章开篇讲清楚，不是削弱成果，而是让读者知道这次工程究竟证明了什么。一个结论越具体，越容易被后续的人复核。

小结：先定比较对象，才谈复刻质量

重写开始前，我们锁定了冻结 OpenAPI 1.12.0、Node v1.0.4 的具体提交和可重复执行的差异验证；把产品规则、协议约束和历史实现拆开登记；将权限、空值、计数、事务后状态与客户端请求路径纳入行为清单。

这些准备决定了 M6 的工程边界：它是一项在已存在系统和消费者面前进行的兼容实现工作，不是自由设计一套新 API。出现差异时，既不为了"复刻"盲目照抄历史，也不借重写的机会擅自更改协议；先给出来源、影响和验证，再做明确选择。

下一篇从 Go 工程结构开始，带你把这个已锁定的目标放进可运行的模块、命令和依赖边界里。接着我们才会讨论契约如何进入 Go、领域层怎样保留输入语义，以及三种数据库怎样各自通过验证。

延伸阅读

• 契约先行：设计一套被七个端复用的 API
• 领域建模：一个文章系统有哪些实体、什么关系
• 接口文档自动化：让 OpenAPI 与代码不脱节
• 质量门禁：契约测试、会话竞态、双运行时与浏览器验收

---

如果这篇文章对你有帮助，欢迎订阅我的 CSDN 专栏 「成为全栈」：

🔗 专栏地址：https://blog.csdn.net/fungleo/category_13204651.html

📦 本系列配套代码仓库：https://github.com/fengcms/become-a-full-stack-developer