为接口实现统一的响应信封

概述

统一的响应信封让客户端只写一份解析逻辑和一套错误处理，不必逐个接口判断。先确定成功结构、错误结构与元数据位置，再在统一点位集中实现，而不是散落在每个控制器里。

关键步骤

1. 成功时返回 { data, meta }，错误时返回 { error: { code, message } }，均由同一辅助函数产出。
2. 用中间件把抛出的错误转换为错误信封，并设置匹配的 HTTP 状态码。
3. 仅在相关时把 trace id、分页游标等放入 meta。
4. 对信封结构做版本管理，并写入接口契约文档。

验证

• 成功响应始终包含 data 与可选 meta。
• 错误响应始终包含 error.code 与人类可读信息。
• HTTP 状态码与错误类别一致（4xx 客户端、5xx 服务端）。
• 没有接口返回裸数组或框架原始错误页。

注意事项

• 信封会带来少量体积开销，流式或二进制响应不适用。
• GraphQL 与 gRPC 使用各自约定，不应套用 REST 信封。

type ApiResponse<T> =
  | { data: T; meta?: Record<string, unknown> }
  | { error: { code: string; message: string } };