类型安全的 API 设计模式：让前后端协作少靠约定、多靠约束

前端团队一旦进入多人协作，API 问题往往不只是“字段名写错”，而是契约在不同环节里逐渐漂移：文档是一套、后端实现是一套、前端消费时又假设成另一套。

类型安全的 API 设计模式，真正要解决的是这种契约漂移。它不是只为了让编辑器少报错，而是为了让接口变更可以被更早发现、更清晰协同。

类型安全先解决“契约共享”，再谈生成效率

很多团队引入类型安全 API，最先关注的是能不能自动生成类型。但如果共享的契约本身不稳定，生成只会放大混乱。

更稳的顺序通常是：

明确输入结构
明确成功响应结构
明确错误结构
明确版本和兼容边界

只有契约稳定后，生成和复用才有意义。

运行时校验不能省，它负责兜住类型之外的真实风险

TypeScript 的类型只存在于开发阶段，真正进入网络传输后，数据仍然可能出错。因此类型安全 API 通常都需要配合 schema 校验。

import { z } from 'zod'

export const ArticleSchema = z.object({
  id: z.string(),
  title: z.string(),
  status: z.enum(['draft', 'published']),
})

export type Article = z.infer<typeof ArticleSchema>

这种模式的关键价值在于：

同一份 schema 同时服务运行时校验和静态类型
不会把“不可信外部数据”直接当成已知类型使用
接口异常更容易被定位到源头

错误模型也应该被设计，而不是临时拼接

很多项目的类型安全只覆盖“成功返回”，一旦进入错误场景就退回 message: string。这会让前端很难做稳定分流。

更实用的错误模型通常至少包括：

code
message
fieldErrors 或 details
traceId 或 requestId

interface ApiError {
  code: 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'RATE_LIMITED'
  message: string
  requestId: string
  fieldErrors?: Record<string, string>
}

错误模型越清晰，前端越能把提示、重试、埋点和排查串起来。