先给签名和用途
标题使用实际的导出名称或请求方法和路径。开头用一句话描述稳定行为,接着给出签名、可用版本和调用位置。异步方法明确何时完成,结果存在排序或分页时明确规则。需要权限、会修改状态或会触发重试的行为应放在调用说明旁。
以示例函数 findEntry 为例,它查询一个内存索引中的条目。
type Entry = { id: string; title: string }
function findEntry(entries: readonly Entry[], id: string): Entry | undefined {
return entries.find((entry) => entry.id === id)
}
解释参数和返回值
| 参数 | 类型 | 要求 | 行为 |
|---|---|---|---|
entries | readonly Entry[] | 必填 | 按数组顺序查找 |
id | string | 必填 | 按原字符串匹配条目标识符 |
找到时返回首个匹配条目,未找到时返回 undefined。区分未传入、空字符串、空数组、null 和 undefined。返回对象有嵌套字段时,交代字段在什么条件下出现。默认值来自实现或约定,参数支持的合法范围也应可核对。
说明 HTTP 接口和错误
HTTP 参考需要解释请求方法、路径参数、查询参数、请求体和响应类型。按对应情况记录状态码、应用错误码与恢复方式。用实际响应说明“成功但结果为空”和“目标不存在”的区别,具体判断依据以接口定义为准。
接口示例使用示例域名和可公开的请求数据。需要验证时,覆盖一个典型成功情况和一个边界或错误情况。用错误与故障排查表达诊断步骤,并将调用签名与上游相同版本的定义关联起来。