用途:为 REST API、GraphQL schema、模块边界、组件 props 等任何代码间交互面提供稳定、难被误用的接口设计指导。
主要能力:契约先行,先定义接口再实现;统一错误语义(如 REST 用 HTTP 状态码加结构化错误体,400/401/403/404/409/422/500 各有含义,不混用模式);在系统边界校验外部输入,内部代码信任类型;优先新增可选字段而非修改或删除已有字段;统一命名约定(REST 用复数名词、查询参数与响应字段用 camelCase、布尔字段用 is/has/can 前缀、枚举用 UPPER_SNAKE)。还涵盖分页、过滤、PATCH 局部更新、判别联合类型、输入输出分离、品牌类型 ID 等模式。
核心原则:Hyrum 定律指出,用户足够多时,所有可观察行为都会被依赖,因此每个公开行为都是潜在承诺,不要泄漏实现细节,设计时就要规划弃用;单版本规则主张避免让消费者在多个版本间选择,应扩展而非分叉。
使用方式:在设计新端点、定义团队间契约、创建组件 props、变更既有公共接口时使用。资料未提供具体安装命令或调用命令。
限制:仅在上游来源与本地项目上下文明确匹配时使用;应用前需验证命令、生成代码、依赖、凭据与外部服务行为;示例不能替代环境特定测试、安全审查,破坏性或高成本操作需用户批准。