技术英语 / 系统课时
解释参数的类型和约束
解释参数的类型和约束
参数说明的价值不在于重复字段名,而在于让调用者知道“能传什么、必须传什么、什么值会被拒绝”。本篇聚焦类型、必填性、范围、默认值和参数依赖,并把这些约束写成可以直接验证的英文参考说明。
学习目标
- 用一致句式表达参数类型、是否必填、取值范围与默认值
- 清楚区分“未提供”“空值”和“使用默认值”这三种情况
- 准确说明参数之间的依赖关系,避免让读者靠猜测组合请求
参数说明至少回答哪些问题
一个参数通常需要回答五类问题:数据类型、是否必填、允许范围或集合、未提供时的行为,以及它与其他参数的关系。不是每个参数都要写满五项,但所有会改变请求合法性的约束都必须出现。
例如只写 “limit: Number of items to return.” 不够,因为调用者还不知道能不能传 0、最大值是多少、缺省时返回多少条。把这些信息放在同一处,能显著减少试错。
用固定顺序组织类型和约束
参数描述可以按“类型与语义 → 必填性 → 范围 → 默认值”的顺序写。英文中不必每次都机械使用完整句式,但信息顺序最好稳定,这样读者扫描多个参数时更快。
片段示例:下面是一个虚构列表接口的参数参考,只用于演示写法;真实项目应以接口契约中的类型和约束为准。
limit
Integer. Optional. The maximum number of items to return.
Must be between 1 and 100. Defaults to 20.
status
String. Optional. One of pending, paid, or canceled.
If omitted, results are not filtered by status.
cursor
String. Optional. The pagination cursor returned by the previous request.
Do not send this parameter on the first request.验证方法是逐项对照接口定义:类型是否一致;可选参数省略后是否确实采用描述中的默认行为;枚举值、上下界和分页规则是否全部匹配。任何无法在契约或测试中证明的限制都不应擅自写入文档。
明确区分缺省值、空值和默认值
optional 只表示参数可以不提供,不等于可以传空字符串、null 或其他“空值”。如果三种情况行为不同,必须分别说明。
例如 “Optional. Defaults to 20.” 表示调用者完全不提供参数时使用 20。如果显式传 null 会报错,就不要写成 “Null values use the default.”。同理,空字符串 "" 可能是合法值,也可能是校验错误,必须按真实契约描述。
范围表达尽量直接使用 between 1 and 100、must be at least 1、must be less than 1000。如果边界是否包含容易误解,优先改写成明确数字条件,而不是依赖读者推断。
写清参数之间的依赖
参数依赖最容易造成“单个字段都合法,但组合起来非法”的请求。常见关系包括 A 出现时 B 必填、A 与 B 互斥、至少提供其中一个,以及某个参数只在另一参数取特定值时生效。
可以直接写成可测试的条件句:
| 关系 | 推荐写法 |
|---|---|
| 依赖 | If endTime is provided, startTime is required. |
| 互斥 | Do not specify cursor and page in the same request. |
| 至少一个 | Provide either email or userId. |
| 条件生效 | sortOrder is used only when sortBy is provided. |
不要写 “These parameters are related.” 之类没有规则的信息。调用者真正需要的是“什么组合有效、什么组合会失败”。
让文档和校验规则保持同一来源
参数文档最危险的问题是与代码逐渐分叉:实现把最大值从 100 改成 200,文档却仍写旧限制。能从 OpenAPI、JSON Schema 或类型定义生成的内容尽量自动生成;需要人工补充的业务语义,则在变更评审中与校验逻辑一起检查。
发布前可以用一个简单问题做最终校验:读者只看参数说明,能否构造出一个确定合法的请求,并知道哪些输入一定会被拒绝?如果答案是否定的,说明类型、边界、默认行为或参数依赖至少缺了一项。