接口规范

NOTE

本文章部分内容引用 Apifox 中的 RESTful Web API 接口设计规范

1. 使用良好的名称

为资源、属性、操作和参数赋予良好的名称对于打造卓越的开发者体验至关重要。

资源由名词描述。资源和属性的名称必须具有描述性且易于客户理解。应使用与用户场景（而非服务实现细节）相对应的名称，例如使用"Diagnosis"（诊断）而非"TreeLeafNode"（树叶子节点）。名称应传达值的目的，而非仅仅描述其结构，例如使用"ConfigurationSetting"（配置设置）而非"KeyValuePair"（键值对）。易于理解源于熟悉感和认知度；您应优先考虑产品门户/用户界面中的名称以及行业标准保持一致。

名称应帮助开发者发现功能，而无需频繁查阅文档。使用常见模式和标准约定有助于开发者正确猜测常见属性名称及其含义。使用详细的命名模式，并避免使用除服务领域中众所周知的缩写词之外的缩写。

✅ 务必尽可能对同一概念使用相同的名称，对不同概念使用不同的名称。

1.1 推荐的命名规范

以下是推荐命名规范：

✅ 务必将集合命名为复数名词或复数名词短语（使用正确的英语）。

✅ 务必将非集合的值命名为单数名词或单数名词短语。

☑️ 应在名称中将形容词置于名词之前（当名称同时包含名词和形容词时）。
例如：collectedItems（收集项），而非 itemsCollected（项收集）。

☑️ 应将所有首字母缩写词视为常规单词进行大小写处理（即采用 lower camelCase 驼峰命名法）。
例如：nextUrl，而非 nextURL。

☑️ 应在日期时间值的名称中使用"At"后缀。
例如：createdAt（创建于），而非 created（创建）或 createdDateTime（创建日期时间）。

☑️ 应对于具有明确度量单位的值（如字节、英里等），在名称中使用该度量单位的后缀。在适当情况下，使用普遍接受的单位缩写（例如，使用"Km"而非"Kilometers"）。

☑️ 应对于时间持续时间使用 int 类型，并在名称中包含时间单位。
例如：使用 expirationDays（过期天数）作为 int 类型，而非使用 expiration（过期）作为 date-time 类型。

⚠️ 不应在资源或属性名称中使用品牌名称。

⚠️ 不应使用首字母缩写词或缩写，除非它们被广泛理解（例如，"ID" 或 "URL" 可以，但不应使用 "Num" 表示 "number"）。

⚠️ 不应使用在广泛使用的编程语言（包括 C#、Java、JavaScript/TypeScript、Python、C++ 和 Go）中的保留字作为名称。

⛔ 禁止在布尔值的名称中使用"is"前缀，例如使用"enabled"（已启用），而非"isEnabled"（是否启用）。

⛔ 禁止在名称中使用冗余词语。
例如：/phones/number（电话/号码），而非 /phone/phoneNumber（电话/电话号码）。

2. HTTP 请求方法

HTTP 协议定义了许多请求方法，这些方法指示要在资源上执行的作。RESTful Web API 中使用的最常见方法是 GET、POST、PUT、PATCH 和 DELETE。每种方法对应特定操作。在设计 RESTful Web API 时，应以符合协议定义、访问资源以及执行动作的一致性进行使用这些方法。

请务必记住，特定请求方法的效果应取决于资源是集合还是单个项。下表包含大多数 RESTful 实现使用的一些约定。

2.1 GET/POST 请求

GET/POST 请求检索指定 URI 处资源的表示形式。响应消息的正文包含所请求资源的详细信息。

GET/POST 请求应返回以下 HTTP 状态代码之一：

HTTP状态代码	原因
200（正常）	该方法已成功返回资源
204（无内容）	响应正文不包含任何内容，例如当搜索请求在HTTP响应中不返回匹配项时
400（错误请求）	客户端在请求中放置了无效数据。响应正文可以包含有关错误的详细信息或指向提供更多详细信息的URI的链接
404（未找到）	找不到请求的资源

3. 请求的类型

以下是与相关描述匹配的属性推荐名称：

名称	描述
string	字符串，用于传输文本数据，如用户名称、电子邮件地址、消息内容等。
integer	整数，用于传输整数值，如用户ID、订单编号、状态码等。
boolean	布尔值，用于传输true/false值，如表示开关状态、是否启用、是否有效等。
number	数字，用于传输数值数据，可以是整数或浮点数。
array	数组，用于传输一组数据，如用户列表、商品列表、订单详情等。

4. 返回响应的类型

返回参数的类型应与请求期望的类型保持一致。当返回参数包含子参数时，这些子参数应被组织在嵌套的JSON对象中。以下是一个示例，展示了如何以结构化的方式返回包含子参数的响应：

{
    "code": 200,
    "data": {
        "id": 1,
        "createTime": 1689571200,
        "nick": "张三",
    }
}

返回参数	类型	说明
code	integer	-
data.id	integer	-
data.createTime	integer	-
data.nick	string	-