api-design

用途：在实现内部逻辑之前，或评审公开 API 表面时使用本技能。目标是为 TypeScript、JavaScript、React、React Native 库设计可预测的公开 API，保持显式类型、稳定语义，公开契约中不出现无关内部细节。若库是 Nitro Module，先用本技能确定公开 TypeScript 与 React API 形状，再用 build-nitro-modules 处理 Nitro 的 spec、原生状态与绑定约束；纯 JS、纯 React 或 React Native JS 库则全程留在本技能。\n\n主要能力与工作流：先勾画面向用户的 TypeScript API，再实现内部。写 2 到 3 个真实调用示例，含错误与清理路径；对照规则检查表面；用仓库的类型检查、lint、文档工具验证导出的 TypeScript，然后再实现。\n\nAPI 形状规则：优先单一事实来源；参数达 3 个以上、同类型原语或可能增长时用选项对象；保持 API 具体，避免接受任意输入形状；避免巨型“什么都做”的对象；简化前先清点需支持的工作流，不要静默丢弃。已知有效状态时用字面量联合、可辨识联合、接口与类型化选项组，避免无类型字典、布尔集群、字符串命令与松散事件。二元选项不要建模为可选的两值字符串联合。不要用一个充满可选字段的接口表示多种对象状态，应使用可辨识联合、继承或独立变体接口，让不可能字段组合无法表示。相关字段应放在其必需变体上。用 undefined 或可选字段表示缺失，仅在“显式无”语义不同时用 null。状态机、加载状态、结果变体优先可辨识联合。涉及协商时，用户意图与解析后状态分开建模；复杂协商优先用排序约束或偏好对象，由内部解析最接近的可用配置并通过返回值、回调或显式解析方法暴露。常用预设用 as const satisfies Record<string, Type> 暴露，接受类型保持结构化。不要暴露调用方已知的环境事实（如仅重复 Platform.OS 的平台字段），除非 API 能返回其他平台产生的数据。不要冻结当前平台支持矩阵，优先运行时能力字段。优先统一选项对象，避免 ios/android 选项包与平台前缀方法。配置字段分为要求与偏好：要求无法满足时抛错，偏好按尽力而为处理并文档化，需要时暴露能力或解析后配置。按稳定语义能力拆分，运行时可用性描述当前是否具备稳定能力，不永久限制形状。能力发现与对象契约分开：工厂返回具体会话或资源后，其基线方法应由构造保证；否则返回更窄类型或创建失败。用 API 对象图编码生命周期转换，避免陈旧状态 API，重配置后返回新句柄并使旧句柄失效。协商后事实用回调或返回的已解析对象。Nitro 支撑的命令式 API 默认把公开 HybridObject 当作 API，不做预解析、枚举翻译或格式归一化的 JS 包装。\n\n公开 API 组织：公开表面拆到聚焦文件或模块，从清晰包入口再导出，避免包罗万象的文件。默认每个文件导出一个公开类型，仅紧密耦合且很少独立导入时合并。包入口只作桶文件，不定义函数、类、hook、组件、常量、分支、副作用或实现逻辑，唯一允许的运行时声明是单行包根，如 export const camera = NitroModules.createHybridObject<Camera>('Camera');。共享字段方法放基接口或基类，子类型只加特有成员。辅助与转换放最小有意义接收者上，集合级辅助仅在集合有领域语义时添加。除非影响调用方式，性能与实现策略不进入公开形状。\n\nTypeScript 与 JavaScript 风格：不要用 void 0 表示 undefined，显式写 undefined。不要用 ??=、||=、&&= 逻辑赋值，优先显式 if 或直接赋值。命名用动词加主语，数值加单位后缀，如 getCurrentSystemTimestampMs()。布尔按角色命名：观察状态、能力或解析配置用 is*、has*、can*、supports*；控制未来行为的选项用 enable*、allow* 或领域动词。React 与 React Native 公开 API 中 use* 保留给 hook。便宜的可观察状态或能力用属性，副作用、昂贵工作、分配、变更、异步边界或可能失败的操作才用方法。名称显式带单位，如 timeoutMs、byteSize、maxRetries、createdAt。避免给每个导出类型机械加包名、模块名或功能名前缀，仅在无前缀在包根导入处有歧义时使用。调用方观察但不设置的公开状态用 readonly；可变属性仅当赋值本身就是预期命令时使用，且必须便宜、同步、不易失败；若设值需要原生协商、权限、I/O、分配或可能失败的验证，则不适合作为可写属性。\n\n限制：以上为技能文档所载规则，具体仓库工具链、命令与版本未在本资料中提供。