api-and-interface-design

API and Interface Design - 稳定接口设计指南

技能概述

API and Interface Design 提供稳定、不易误用的接口设计完整指南，帮助开发者和架构师设计从REST API到GraphQL接口、从模块边界到组件属性的各种公共接口，让正确的使用方式变得简单，错误的使用方式变得困难。

适用场景

1. 设计API端点

当您需要创建REST或GraphQL API时，本技能提供契约优先设计方法、一致的错误处理语义、分页和过滤规范，确保API稳定且易于文档化。适用于微服务架构、开放平台、前后端分离项目。

2. 定义模块边界和团队契约

在划分微服务边界、建立团队间接口、或设计内部模块依赖时，使用单版本规则避免依赖冲突，用类型化的接口契约保障跨团队协作的稳定性，防止Hyrum's Law导致的行为耦合。

3. 修改现有公共接口

当需要在不破坏现有消费者的情况下扩展API时，本技能指导如何通过添加可选字段而非删除或修改现有字段来保持向后兼容，同时规划合理的废弃迁移策略。

核心功能

1. 契约优先设计原则

在实现前明确定义接口契约，包括输入输出类型、错误响应格式、分页结构和验证规则。适用于REST端点、GraphQL Schema、TypeScript接口、数据库模式设计，确保类型即文档。

2. 一致的错误处理语义

统一的错误响应格式（HTTP状态码 + 结构化错误体），涵盖400客户端错误、401未认证、403无权限、404未找到、409冲突、422验证失败、500服务器错误，避免消费者面对不同错误格式时的困惑。

3. 边界验证策略

在系统边界（API路由、表单提交、外部服务响应、环境变量）验证外部输入，内部代码间依赖类型契约信任已验证数据，特别是第三方API响应必须始终视为不可信数据，避免验证散落在内部代码中。

常见问题

什么是Hyrum's Law，它如何影响API设计？

Hyrum's Law指出：当API的用户足够多时，系统的所有可观察行为都会被某些用户依赖，不管你在契约中承诺了什么。这意味着即使错误消息文本、响应时序、字段顺序这些未文档化的行为，一旦用户依赖就成了事实契约。因此设计时要刻意控制暴露的可观察行为，不泄露实现细节，从设计时就规划废弃策略。

为什么API设计要契约优先？

契约优先让接口定义成为可评审、可讨论的规格说明，实现只是兑现契约。这样做的好处是：类型即文档，消费者能基于类型安全调用；实现前发现设计问题，避免重构；变更时先评估契约影响，防止破坏现有用户；支持并行开发，消费者基于契约Mock，提供者基于契约实现。

REST API和GraphQL接口设计有什么区别？

REST API使用资源和HTTP方法（GET/POST/PATCH/DELETE），适合标准化 CRUD 操作，天然支持HTTP缓存和分层代理，端点命名用复数名词无动词。GraphQL用单一端点和Schema定义，适合复杂查询和减少请求次数，客户端精确获取需要字段，但需要设计Query/Mutation/Subscription结构和类型系统。两者都应遵循契约优先、一致错误处理、边界验证原则。