成为全栈·Go 后端篇·换后端不改前端：四个客户端如何做兼容回归
后端实现换了，客户端可以不改源码，但这不代表只要 API 地址能访问就算兼容。登录载体、响应边界、缓存状态、上传和平台传输都要沿原请求链实际跑一遍。
测试快照：Go 提交 ceac4e0；四客户端默认 API 地址与源码未改；验证范围是请求/会话层 smoke。
前言：复用客户端代码是一项需要证明的结果
为了让"换后端不改前端"这句话站得住，我没有改任何一端的 API 地址，只把测试目标指向本地 Go 服务，然后逐个客户端把常用流程点了一遍。
M6 的目标之一是用 Go 复刻 Node 后端，使网站、管理后台、Taro 小程序和 Flutter App 继续使用相同契约。理想结果是客户端业务代码无需修改，切换本地 base URL 后即可连接 Go。要证明这件事，不能只用 curl 请求健康检查，也不能只看 OpenAPI 文件没有变化。
每个客户端都有自己的认证和传输路径：网站使用同源请求与 Cookie 刷新；管理后台有后台资格与会话守卫；Taro 处理小程序平台的请求、存储与缓存；Flutter 使用 Dio、内存 token 和 refresh retry。上传、评论、投稿和通知还会经过不同的请求封装。
本文按跨客户端共用工作流组织 smoke 测试，并说明"真实请求层"和"完整 UI 验收"之间的边界。
一、第一步不是改 API，而是切换测试地址
客户端代码默认 API 配置继续指向既有服务。回归时用本地环境配置把请求目标指向 Go server，保留生产默认地址不变。这样测到的是已有 API client 与既有 Go endpoint 的契约兼容，而不是为了 Go 临时修改请求格式后再自证通过。
本地测试后端要用独立数据库和固定 fixture。测试账号、文章、评论、附件不能连生产数据；微信登录使用受控身份替身；上传用 local storage 或可控 Provider。不同客户端必须使用一致的 seed、时间和权限角色，才能比较相同行为。
测试地址配置本身也需复核：构建环境、代理和服务端 CORS 可能影响实际请求。客户端把环境变量读成 URL 并不证明请求已经发到目标 Go 实例；应检查请求日志和测试 server 记录。
具体到四个客户端，地址注入的方式并不一样，这也决定了"切到 Go"到底要改哪一层：
| 客户端 | 默认地址 | 地址配在哪 | 切到 Go 改什么 |
|---|---|---|---|
| 网站 web-frontend | /api/v1（相对路径） |
next.config 的 API_ORIGIN |
只改这个变量 |
| 管理后台 manage-frontend | /api/v1（相对路径） |
vite proxy 的 API_TARGET |
只改这个变量 |
| Taro 小程序 | 绝对地址 | TARO_APP_API_BASE |
设环境变量 |
| Flutter App | 绝对地址 | --dart-define=API_BASE_URL |
改编译参数 |
前两行是同一套思路：源码里只有相对路径，真正的后端地址藏在代理配置里。
js
// web-frontend/next.config.ts
async rewrites() {
// 浏览器端默认 /api/v1（同源）；本规则把它代理到后端 API_ORIGIN
const origin = process.env.API_ORIGIN || 'http://127.0.0.1:11001'
return [
{
source: '/api/v1/:path*',
destination: `${origin}/api/v1/:path*`,
},
]
}
ts
// manage-frontend/vite.config.ts
const API_TARGET = process.env.API_TARGET ?? 'http://localhost:11000'
proxy: {
'/api/v1': {
target: API_TARGET,
changeOrigin: true,
secure: true,
},
'/files': {
target: API_TARGET,
changeOrigin: true,
secure: true,
},
}所以对网站和后台来说，"换后端"改的是代理指向，请求代码一行没碰。这也解释了它们为什么天然不容易串环境：浏览器看到的永远是自己的域名。
但省事的地方恰好也是最容易误判的地方。同源代理把跨域问题在服务端消化掉了，curl 打得通、页面能出数据，并不等于真实浏览器里的 Cookie 策略也被验证过------SameSite、Secure、跨站携带仍需在真实域名和 HTTPS 下单独看。
Flutter 那边相反，约束是硬的：
dart
const configured = String.fromEnvironment(
'API_BASE_URL',
defaultValue: 'https://api.example.com/api/v1',
);
if (kReleaseMode && !configured.startsWith('https://')) {
throw StateError('Release requires an HTTPS API_BASE_URL');
}release 构建只接受 https://，把 --dart-define 指到本地 http://127.0.0.1 会直接抛异常。所以本地 smoke 只能用 debug 构建，或者给本地服务加一层 TLS 反代。这条约束不是为回归临时加的，它本来就在客户端里------撞上它反而说明代码没被改过。
二、按工作流覆盖共性能力
推荐建立一条端到端但隔离的内容工作流：
- 匿名读取首页、搜索和已发布文章；
- 注册/登录，验证 access token 与 refresh 载体；
- 读取会员资料，更新资料，测试未提交与空值；
- 创建草稿、投稿、上传附件、提交审核；
- 管理员审核后确认公开读取和通知；
- 对文章点赞、收藏、报告阅读历史；
- 留言并回复，审核后查看评论通知；
- 退出，验证客户端清理会话及后续受保护请求拒绝。
流程覆盖请求与返回结构、业务权限和关键状态，不必让每个客户端重复所有相同后置断言。服务端领域测试确保数据库不变量；客户端 smoke 确认现有代码能调用并理解响应。
小程序微信闭环额外使用固定 openid：测试客户端走真实 API 请求模块，后端微信 HTTP 使用注入替身；同一个身份重复登录不能再建号，首次设密后 Flutter 用相同用户名密码登录。该场景证明站内账号复用，不证明真实微信网络已联通。
三、每个客户端需要看自己的会话边界
网站 web-frontend 使用真实 request core 和 Zustand 会话状态，测试登录、读取、Cookie refresh、互动、投稿、上传、评论回复、通知和登出。测试浏览器/请求环境的 Cookie 模拟不能完全代替真实浏览器 SameSite、Secure、跨域与代理策略，所以报告明确这是请求层证据。
管理后台使用现有 request core 和真实会话代码，角色为管理员，覆盖后台 API 操作。页面按钮是否正确禁用、导航状态和交互体验，需要浏览器逐页面验收；本轮 smoke 不是 UI 全回归。
Taro 运行 api.ts、session 与缓存代码，验证基础访问、刷新、投稿和通知。由于平台 request 与 storage API 需要小程序运行环境，本地回归对传输/存储层使用测试替身；这不等于微信开发者工具完整预览和真机网络验收。
Flutter 使用真实 Dio 网络请求、内存 TokenVault 和失效令牌 refresh retry，覆盖互动、投稿及跨客户端创建账号登录。Dio 路径是真实 HTTP 客户端代码，但这也不等于所有文章、会员、设置页面都由模拟器手工走查。
四段文字压成一张表，读的时候不容易把"真实"和"替身"看串：
| 客户端 | 真实执行的部分 | 使用替身的部分 | 本轮未覆盖 |
|---|---|---|---|
| 网站 | request core、Zustand 会话、Cookie 刷新 | 无（请求层真实） | 真实浏览器 SameSite/Secure、跨域策略 |
| 管理后台 | request core、真实会话与角色 | 无 | 按钮禁用态、导航状态、交互体验 |
| Taro | api.ts、session、缓存代码 | 平台 request 与 storage | 开发者工具预览、真机网络 |
| Flutter | Dio 网络栈、TokenVault、refresh retry | 无 | 各业务页面的模拟器走查 |
第三列的空白比第二列更值得盯。替身是主动选择，未覆盖是欠账；两者混在一句话里写，验收报告就会显得比实际完成度高。
四、缓存和乐观更新要避免串账号
后端切换会改变服务端返回时序，客户端缓存仍可能把旧 Node 响应展示出来。回归应检查切换 base URL 后缓存 key 是否清理，用户登出/换账号后私有 query 是否隔离，互动 mutation 是否失效或更新相关缓存，以及失败时乐观状态是否回滚。
不同客户端缓存机制不同：Taro 有本地与内存缓存，Flutter 以仓库/Provider 的读取路径缓存，Web/后台使用各自请求状态管理。不能把后端返回 200 当作页面统计数字已经刷新；要测试 mutation 后 UI 数据流与私有身份状态。
Flutter 这边有一层天然保护，很容易被忽略：token 保险箱的命名空间直接取自 API 地址的主机名。
dart
final api = ApiClient(
baseUrl: configured,
vault: SecureTokenVault(namespace: Uri.parse(configured).authority),
);主机名一变，命名空间就变，旧环境存下的 token 根本读不出来。好处是不会把 A 环境的凭据带进 B 环境，代价是回归时必须重新登录。所以 smoke 里出现"指到 Go 之后立刻要求登录"是预期行为，不是兼容性问题；反过来，如果它拿着旧 token 把请求打通了，那才要查------请求究竟发给了谁。
测试阶段可以用独立存储 namespace 或清空测试数据，但生产客户端不应因 M6 将个人缓存迁移逻辑做无理由改造。此次目标是保留已有协议，让新后端满足调用者预期。
五、响应体与错误码回归
端到端 smoke 不应只检查 status=200。要确认成功 envelope 的 code/data/requestId/timestamp 结构、错误码与 HTTP 状态、空集合是 \[\]、可空字段/null 语义、分页元数据、Cookie 属性、上传 URL 与 content-type。重放错误 token、权限不足、草稿公开读取和字段校验错误可以覆盖会影响客户端分支的响应。
这些检查项列出来容易，落地时常被跳过。补一列"漏了会怎样"，就知道哪几项不能省：
| 要确认的 | 常见的错法 | 客户端会怎么误判 |
|---|---|---|
envelope 的 code/data/requestId |
少一个 requestId |
日志对不上，出问题无法串起来 |
| 错误码与 HTTP 状态 | HTTP 200 里塞业务错误码 | 拦截器按状态码判成功，页面白屏 |
| 空集合 | 该给 [] 时给了 null |
列表渲染直接报错 |
| 可空字段 | 该 null 时给空字符串 |
前端把空串当成"用户清空了" |
| 分页元数据 | total 与实际条数不符 |
翻到底还显示有下一页 |
| Cookie 属性 | 少了 SameSite/Secure |
跨站场景静默不发送，登录态莫名丢失 |
| 上传 URL 与 content-type | 返回相对路径或错 MIME | 图片裂开、下载变乱码 |
右列这些现象的共同点是：都不会抛异常。接口返回 200、页面正常渲染，只是数据不对------这类问题最难在上线后归因，所以宁可在 smoke 里逐项对一遍。
四端可能处理错误有不同表现：Web/后台可能触发 refresh 单飞，Taro 可能清理本地 token，Flutter 可能进入重新登录状态。回归时记录每端看到的行为，确保服务端错误不让一个端误判成功或永久保留旧会话。
六、把限制写进验收报告
M6 客户端证据分成三类：现有请求/会话代码执行；平台传输替身辅助执行；人工 UI/真实外部平台验收。本轮完成了第一类及部分第二类，没有声称所有页面、真实微信开发者工具、线上 R2、完整浏览器 Cookie 或真实生产网络已验收。
这类分级不是降低标准，而是让后续工作列表能准确接上。若即将切换真实流量，需要补全 Taro 开发者工具路径、真实浏览器 Cookie 端到端、附件 CDN/R2、Android/iOS 页面验收和生产反向代理配置。每项都应写明账号、环境和不触碰真实用户数据的安全方式。
小结：后端可替换性要通过原客户端来检验
M6 没有改 OpenAPI、Node 源码或四端 API 默认地址，而是将客户端测试目标指向隔离的 Go 服务。网站、后台、小程序与 Flutter 的已有请求和会话路径覆盖常见业务；微信使用固定身份替身，Taro 平台传输使用替身，Flutter 使用真实 Dio。
写兼容结论时，尽量描述执行了什么代码、通过什么 transport、覆盖哪些功能、哪些外部环境仍未测。后端换实现的价值，最终要由原有消费者可以继续运行来证明。
延伸阅读
如果这篇文章对你有帮助，欢迎订阅我的 CSDN 专栏 「成为全栈」：
🔗 专栏地址：https://blog.csdn.net/fungleo/category_13204651.html
📦 本系列配套代码仓库：https://github.com/fengcms/become-a-full-stack-developer
