用途:帮助在 API 设计与实现阶段,按数据形态、所有权与运行时约束选择协议,规范边界、客户端层、错误处理与安全基线。适用于定义或重构 API 边界、前端与服务端数据获取策略不明确、实时传输选型阻塞实施等场景。
协议选择指引:REST 适合标准 CRUD、广泛客户端兼容与简单缓存;GraphQL 适合灵活读模型、多客户端数据组合与 schema 治理;WebSocket 适合低延迟双向实时通道;SSE 适合仅需服务端到客户端流式推送;tRPC 适合 monorepo 内端到端 TypeScript 契约。资料提醒避免在没有清晰边界时混用模式。
实施流程:一、定义 API 契约,明确资源所有权、版本策略、请求/响应结构与错误模型,统一认证、分页、过滤与幂等。二、选择传输,REST 用于核心 CRUD,GraphQL 用于查询组合,WebSocket/SSE 用于实时更新,tRPC 在需要共享 TS 类型且服务边界允许时使用。三、标准化客户端层,包括集中式客户端工厂与拦截器、类型化 API 封装、统一重试/超时与认证刷新逻辑,并按端点组记录缓存与失效规则。四、错误与可观测性,统一错误信封、关联 ID 与请求追踪,分别记录校验失败与传输失败。五、安全基线,在 API 边界校验输入 schema,按资源/动作级别执行授权,并施加限流与负载大小限制。
代理输出要求:推荐传输及理由、端点/schema 提案、客户端集成模式、必要时给出实时模型、安全与测试清单。
限制:资料仅给出流程与方法指引,未提供具体代码模板、库版本或平台支持细节;完整模板位于 references/guide.md,正文未展开。价格与收费信息暂未提供。