前后端对接闭环 —— 把「契约」跑通
契约篇。前面三篇分别是 语言、框架、Bean。这一篇不再堆新概念,而是把请求从页面打到门面再回来的协议讲清楚。
文中前端 / admin、BFF、下游服务都是脱敏后的契约教学示例。分页字段
data.module、用 200 包业务失败,都是这一份示例约定,不是业界普遍规范。没有对照过某份私有源码。
0. 定位
语言篇 你会写 Java
框架篇 你懂 Spring 怎么把对象和 HTTP 接起来
Bean篇 你知道容器里躺着的是实例
契约篇 前端和后端靠同一份协议协作
前后端是两个运行时。沟通不是函数调用,是约定:
- 正文怎么包一层信封
- 错误码两边同一套 wire 值
- 登录失败是 HTTP 401 还是信封里的业务码——必须写死,不能靠「行业常识」
1. 请求全景
一次「保存权益」的教学路径:
flowchart TD
subgraph FE[前端 admin]
A1[页面]
A2[统一 HTTP client]
A3[解包信封]
A4[更新 UI]
A1 --> A2 --> A3 --> A4
end
subgraph BFF[BFF / HTTP]
B1[Controller]
B2[Manager 编排]
B3[Client 调下游]
B1 --> B2 --> B3
end
subgraph DOWN[下游]
D1[权威服务 RPC]
D2[数据库]
D1 --> D2
end
FE --HTTPS JSON--> BFF
BFF --RPC--> DOWN
BFF 不一定自己写 Mapper。数据常常在下游。返回信封 → 前端解包 → UI。
2. 一次保存 / 发布的旅程
教学用的路径集中放一处,避免散落魔法字符串:
// 脱敏教学示例
export const BENEFIT_API = {
saveAndPublish: "/api/v1/benefits/save-and-publish",
remove: (id: string) => `/api/v1/benefits/${encodeURIComponent(id)}`,
};
@RestController
@RequestMapping("/api/v1/benefits")
public class BenefitController {
private final BenefitManager benefitManager;
public BenefitController(BenefitManager benefitManager) {
this.benefitManager = benefitManager;
}
@PostMapping("/save-and-publish")
public ApiResult<BenefitDto> saveAndPublish(@Valid @RequestBody SaveBenefitForm form) {
return ApiResult.success(benefitManager.saveAndPublish(form));
}
}
Manager 做校验和编排,再调 BenefitClient(RPC)。不要假装 @Transactional 会把下游 RPC 一起回滚——本地库和远程是两条边界。成功才 ApiResult.success;前端 unwrap 后再画 UI。
3. ApiResult<T>:类型安全的解包
后端工厂(与框架篇同一套教学信封):
public enum ResultCode { SUCCEEDED, FAILED, UNKNOWN }
public record ApiResult<T>(ResultCode resultCode, String errorCode, String errorMsg, T data) {
public static <T> ApiResult<T> success(T data) {
return new ApiResult<>(ResultCode.SUCCEEDED, null, null, data);
}
public static <T> ApiResult<T> fail(String code, String msg) {
return new ApiResult<>(ResultCode.FAILED, code, msg, null);
}
public static <T> ApiResult<T> unknown(String code, String msg) {
return new ApiResult<>(ResultCode.UNKNOWN, code, msg, null);
}
}
JSON 例:
{
"resultCode": "SUCCEEDED",
"errorCode": null,
"errorMsg": null,
"data": { "id": "b-1", "title": "满减" }
}
删除成功时 data 可以是 null。前端必须允许成功且无 body。
3.1 只认 resultCode,缺了不是失败
下面这份 TS 把「根本不是信封」和「业务三态」分开。缺失 / 陌生值 / 字段冲突不当成 FAILED,也不诱导去点「再试一次写入」。
type ResultCode = "SUCCEEDED" | "FAILED" | "UNKNOWN";
type Ok<T> = { kind: "ok"; data: T | null };
type Failed = { kind: "failed"; errorCode: string; errorMsg: string };
type Pending = { kind: "pending"; errorCode?: string; errorMsg?: string };
type ProtocolError = { kind: "protocol"; reason: string };
type Unwrapped<T> = Ok<T> | Failed | Pending | ProtocolError;
function isRecord(v: unknown): v is Record<string, unknown> {
return typeof v === "object" && v !== null;
}
export function unwrapEnvelope<T>(json: unknown): Unwrapped<T> {
if (!isRecord(json) || !("resultCode" in json)) {
return { kind: "protocol", reason: "not-an-envelope" };
}
const code = json.resultCode;
if (code !== "SUCCEEDED" && code !== "FAILED" && code !== "UNKNOWN") {
return { kind: "protocol", reason: "unknown-resultCode" };
}
// 若同时带了派生布尔,必须和 resultCode 一致,否则当协议错误,避免各读各的
if ("success" in json && json.success === true && code !== "SUCCEEDED") {
return { kind: "protocol", reason: "conflicting-flags" };
}
if (code === "SUCCEEDED") {
return { kind: "ok", data: (json.data as T) ?? null };
}
if (code === "FAILED") {
return {
kind: "failed",
errorCode: String(json.errorCode ?? ""),
errorMsg: String(json.errorMsg ?? ""),
};
}
return {
kind: "pending",
errorCode: String(json.errorCode ?? ""),
errorMsg: String(json.errorMsg ?? ""),
};
}
规则:
| 情况 | 怎么处理 |
|---|---|
| HTTP/网络失败、非 JSON | 不是业务信封,走网络层,不要 unwrap |
JSON 没有 resultCode |
protocol,不是 FAILED |
陌生 resultCode |
protocol |
派生布尔和 resultCode 打架 |
protocol |
SUCCEEDED |
读 data,允许 null |
FAILED |
业务失败,按 errorCode 分流 |
UNKNOWN |
未决:可能已经成功,禁止盲重视写入 |
4. 错误码:以线上值为准
两端枚举名字可以不同,wire 上的字符串必须一致。教学里的兼容层(虚构,不是某家 RPC 商标):
enum TimeoutWire {
TIMEOUT = "TIMEOUT",
// 旧协议曾下发这个值,前端映射到同一处理分支
LEGACY_TIMEOUT = "LEGACY_TIMEOUT",
}
可以靠 OpenAPI / JSON Schema 生成类型、再加契约测试,减少两份手抄漂移。不是只能手抄。
errorMsg 有时被旧协议复用成「去登录的 URL」。现代设计请拆开:message、redirectUrl、action。前端:
- 按
errorCode分流:未登录 / 无权限 / 乐观锁冲突 / 一般提示 - 不要 Toast 一段 URL
- 不要直接
location.href = errorMsg - 即便有
redirectUrl,也要过第 7 节的白名单
5. 分页信封
本例 data 是分页容器,列表在 module:
{
"resultCode": "SUCCEEDED",
"data": {
"module": [
{ "id": "1" }, { "id": "2" }, { "id": "3" }, { "id": "4" }, { "id": "5" },
{ "id": "6" }, { "id": "7" }, { "id": "8" }, { "id": "9" }, { "id": "10" }
],
"totalCount": 42,
"pageNo": 1,
"pageSize": 10,
"hasNext": true,
"nextStartRowKey": "10"
}
}
第一页 10 条、总共 42、hasNext: true,数量是对得上的。module 不是所有后端列表的通用字段。 别的系统可能是 records / items / list。不要写 data.map,除非契约就是数组。
6. 删除
路径里的动态段要编码:
await post(BENEFIT_API.remove(id)); // encodeURIComponent 已在拼路径时做
用 POST /delete 还是 HTTP DELETE 是契约选择,选一种写进文档。链路仍是 Controller → Manager → Client。返回 ApiResult<Void>(成功 data: null)。
Controller 只从统一出口出信封。全局异常处理:超时 / 未知不能一律 FAILED(框架篇第 9 节)。
7. HTTP 状态、来源页、可信回跳
7.1 两层状态
这份兼容示例可能用 HTTP 200 包业务 FAILED(未登录也走信封)。这不是推荐所有鉴权都 200。网关、反向代理、鉴权中间件仍会 401/403。client 要同时看 response.ok 和信封。
7.2 X-Page-Url 和 Referer
登录成功要跳回「刚才那一页」(含 hash 路由):
- 首选:前端每个请求注入
X-Page-Url: window.location.href(包含 hash) - 回退:浏览器
Referer - 再回退:当前请求 URL(通常没有前端 hash)
Referer 是 forbidden 请求头,页面脚本不能 headers.set("Referer", ...)。要用 fetch(url, { referrer, referrerPolicy })。跨域时策略可能只剩 origin,永远没有 fragment。自定义头要过 CORS Access-Control-Allow-Headers,预检会多一次 OPTIONS。
不要把 token、敏感 query 拼进会被上报的页面 URL。
7.3 白名单(前后端都做)
错误示范:host.endsWith("example.com") 会放行 evil-example.com。
function isTrustedGuideUrl(raw: string, trustedSite = "example.com"): boolean {
let u: URL;
try {
u = new URL(raw.trim());
} catch {
return false;
}
if (u.protocol !== "https:") return false; // 生产建议仅 https
if (u.username || u.password) return false;
if (u.port && u.port !== "443") return false;
if (raw.length > 2048) return false;
const host = u.hostname.toLowerCase();
const ok =
host === trustedSite || host.endsWith("." + trustedSite);
// example.com 与 foo.example.com 过;evil-example.com、example.com.evil 不过
return ok;
}
示例域用 example.com。拒绝 evil-example.com、example.com.evil。query 保持编码,不要二次解码成开放重定向。
8. UNKNOWN:可能已经成功
超时不等于 FAILED。写操作收到 UNKNOWN / 协议未决时:
- 禁止自动再提交一笔会改状态的请求
- 用
requestId/ 幂等键去查询,或等后台对账 / 异步确认 - 在幂等与协议允许时,可以安全重试查询;不要把「全世界只能让用户手工刷新」写成唯一动作,但 UI 上引导「先看结果再决定」通常最稳
- 只读 GET 和写入不同;已知 FAILED 也未必适合自动重试(乐观锁冲突要刷新,不要盲打)
幂等本身见专栏 幂等。
9. Mock 和真实后端
示例命令(不是某内部包管理器):
npm run dev # 本地 mock
MOCK=none npm run dev # 关掉 mock,打真实 BFF
Mock 和实现漂移是风险,不是应接受的常态。以审定契约为准:不一致时先确认谁错,不要默认「后端一定对」或「改 mock 让页面绿」。Schema、生成 types、mock、契约测试应对齐同一份定义。
10. 自测
1. JSON 没有 resultCode,当成 FAILED 去 Toast 可以吗?
不可以。那是协议错误或根本不是信封。缺失状态当未决 / protocol,不要诱导写入重试。
2. 登录失败把 URL 放进 errorMsg,直接 Toast 或跳转?
不要 Toast URL。跳转必须走独立字段并过白名单。这是旧协议兼容,不是推荐设计。
3. 为什么还要 X-Page-Url?Referer 不够吗?
Referer 脚本设不了、跨域常只剩 origin、没有 hash。SPA 回跳现场要自己带当前页(含 fragment),并当成不可信输入校验。
4. 列表一定是 data.module 吗?
只是本例。先读契约。数量要和 pageSize / totalCount 对得上。
5. Mock 绿了就能发吗?
不能。Mock 只保证前端自洽。联调以真实实现 + 契约为准。
11. 四篇 checklist
| 篇 | 你该能做到 |
|---|---|
| 语言 | 类、集合、异常、Stream、多态写得出 |
| 框架 | 起一个 Boot 服务,Controller → Service → Mapper,本地事务边界清楚 |
| Bean | 说清 Class / 定义 / 实例,不把事务神话成「只有 Service 能用」 |
| 契约 | 解包三态、错误码分流、回跳校验、UNKNOWN 不盲写 |
读完这四篇,还不能等价于「已经能独立交付生产中后台」。还要补专栏里的事务、锁、幂等、查询、二方包。
12. 收束
契约是前后端唯一的共同语言。信封、错误码、分页字段、鉴权跳转,全部写进文档和测试,而不是写进口头习惯。
13. 术语表
| 术语 | 一句话 | 前端锚点 |
|---|---|---|
| 契约 | 双方遵守的请求/响应形状 | 一份 OpenAPI 或共享 types |
resultCode |
SUCCEEDED / FAILED / UNKNOWN | 只认这一字段做三态 |
| UNKNOWN | 未决,可能已成功 | 禁止盲写重试 |
errorCode |
线上字符串 | 不要对枚举名 |
errorMsg / redirectUrl |
文案 vs 跳转 | 旧协议可能混在 msg 里 |
ApiResult / 分页 module |
本例信封 | 列表走 data.module |
| BFF | HTTP 门面 | 前端只打这一层 |
X-Page-Url |
当前页(含 hash) | 请求拦截器注入 |
| Referer | 浏览器来源头 | forbidden header,无 fragment |
| 开放重定向 | 把不可信 URL 当跳转 | 白名单精确匹配域名 |
| 幂等键 / requestId | 同一笔业务的身份证 | 查询和重试用 |
| Mock | 本地桩 | 不能替代契约测试 |
上一篇:Spring Bean 进阶 · 语言 / 框架:Java · Spring Boot
评论