api接口开发规范

API 接口开发规范

一、接口设计原则

（一）一致性原则

1、命名规范：接口的路径、参数名、返回字段名等应遵循统一且清晰的命名规则，使用复数形式表示集合资源（如/users），采用驼峰式命名法，避免使用特殊字符和难以理解的缩写。

示例	说明
获取用户列表接口	GET /users，其中users明确表示操作对象是用户集合

2、数据格式：规定统一的请求和响应数据格式，如 JSON 格式，在 JSON 数据中，字段顺序保持一致，日期格式统一为“YYYY-MM-DD”或特定的时间戳格式（如 Unix 时间戳）。

|示例|说明|

|用户信息返回格式|{ "id": 1, "name": "John Doe", "email": "john.doe@example.com", "created_at": "2024-01-01T00:00:00Z" }|

（二）简洁性原则

1、接口功能单一：每个接口应专注于完成一个明确的功能，避免在一个接口中处理多种复杂逻辑，获取用户信息和更新用户信息应分别设计为两个独立的接口。

接口名称	功能描述
GetUserInfo	根据用户 ID 获取用户的详细信息
UpdateUserInfo	根据用户 ID 更新用户的特定信息（如姓名、邮箱等）

2、参数精简：仅提供必要的参数，避免过多的冗余参数，对于可选参数，应明确其默认值或通过合理的逻辑判断是否传递。

|示例|说明|

|获取订单详情接口参数|GET /orders/{order_id}，仅需要订单 ID 即可获取订单详情，无需其他多余参数|

（三）安全性原则

1、身份认证与授权：对需要保护数据的接口，必须进行身份认证和授权，常见的方式包括 API Key、OAuth 2.0 等，确保只有经过授权的用户或应用能够访问敏感数据。

认证方式	描述
API Key	用户在调用接口时，需在请求头中携带预先分配的 API Key，服务器验证 Key 的有效性来确认用户身份
OAuth 2.0	通过第三方授权服务器，让用户登录并授权应用获取其部分资源访问权限，适用于涉及多方数据交互的场景

2、数据加密：在传输过程中，对敏感数据（如用户密码、银行卡信息等）进行加密处理，防止数据被窃取或篡改，通常采用 HTTPS 协议进行数据传输加密。

数据类型	加密方式
用户密码	使用哈希算法（如 bcrypt、MD5 等）对密码进行加密存储，传输时可进一步使用 SSL/TLS 加密通道
银行卡号	采用 AES、RSA 等加密算法对银行卡号进行加密传输，确保数据安全

二、接口定义规范

（一）HTTP 方法选择

HTTP 方法	描述	适用场景
GET	用于获取资源信息，不应产生副作用（如修改数据），请求参数通常放在 URL 查询字符串中，适用于查询类操作，如获取用户列表、获取商品详情等。	当客户端需要从服务器获取某些数据但不改变服务器状态时使用，例如GET /products?category=electronics获取电子产品类商品列表
POST	用于创建新资源或提交数据进行处理，请求体中包含要创建或处理的数据，适用于创建用户、提交订单等操作。	当客户端需要向服务器发送数据以创建新资源或触发特定业务逻辑时使用，例如POST /users创建新用户，请求体中包含用户信息（如姓名、密码、邮箱等）
PUT	用于更新指定资源的全部信息，请求 URL 中包含资源的 ID，请求体中包含更新后的数据，适用于更新用户信息、修改商品库存等操作。	当客户端需要对服务器上的特定资源进行全面更新时使用，例如PUT /users/1更新 ID 为 1 的用户信息，请求体中包含新的用户信息（如新的姓名、邮箱等）
DELETE	用于删除指定资源，请求 URL 中包含资源的 ID，适用于删除用户、下架商品等操作。	当客户端需要从服务器删除特定资源时使用，例如DELETE /users/2删除 ID 为 2 的用户
PATCH	用于更新指定资源的部分信息，请求 URL 中包含资源的 ID，请求体中仅包含需要更新的字段及其新值，适用于局部更新用户资料、调整订单状态等操作。	当客户端只需要更新服务器上特定资源的部分字段时使用，例如PATCH /users/3更新 ID 为 3 的用户的部分信息（如仅更新用户头像），请求体中仅包含头像的新 URL

（二）接口路径设计

1、资源导向：接口路径应以资源为中心进行设计，反映资源的层次结构和关系，对于博客系统，文章资源的路径可以是/articles，评论资源的路径可以是/articles/{article_id}/comments。

资源类型	路径示例	说明
文章	/articles	获取文章列表或进行文章相关操作的基础路径
文章评论	/articles/{article_id}/comments	在特定文章下获取评论列表或进行评论相关操作的路径，体现评论与文章的关联关系

2、使用名词复数形式：一般情况下，接口路径中的资源名称使用名词复数形式，表示资源的集合，如果资源是单个实体，则在路径变量中体现。

|示例|说明|

|获取所有分类|GET /categories|categories为复数形式，表示获取所有分类的集合|

|获取某个分类详情|GET /categories/{category_id}|通过分类 ID 获取单个分类的详细信息|

（三）请求参数规范

1、路径参数：使用花括号{}括起路径中的变量部分，用于在 URL 中动态传递参数值，路径参数通常用于标识唯一的资源或执行特定操作所需的关键信息。

|示例|说明|

|获取用户信息接口|GET /users/{user_id}，其中{user_id}为路径参数，用于指定要获取信息的用户的唯一标识符|

2、查询参数：在 URL 的查询字符串部分传递参数，用于对资源进行筛选、排序、分页等操作，查询参数应以键值对的形式出现，多个参数之间用&连接。

|示例|说明|

|分页获取商品列表接口|GET /products?page=1&page_size=10&sort_by=price&order=asc，其中page表示页码，page_size表示每页显示数量，sort_by表示排序字段，order表示排序顺序（升序或降序）|

（四）请求头规范

1、内容类型（Content-Type）：在 POST、PUT、PATCH 等请求中，需要在请求头中指定Content-Type，表明请求体的数据格式，常见的值为application/json（表示 JSON 格式数据）、application/xml（表示 XML 格式数据）等。

请求方法	Content-Type 示例	说明
POST	application/json	表示请求体中的数据为 JSON 格式，例如在创建用户时，请求体可能包含用户信息的 JSON 数据
PUT	application/xml	表示请求体中的数据为 XML 格式，适用于一些特定的企业级应用或对数据格式有严格要求的场景

2、接受类型（Accept）：客户端在请求头中可以使用Accept字段告知服务器期望接收的数据格式，服务器应根据客户端的请求返回相应格式的数据，常见的值为application/json、application/xml等。

|示例|说明|

|获取用户信息时希望返回 JSON 格式数据|Accept: application/json，服务器收到该请求后，会尽量以 JSON 格式返回用户信息数据|

三、响应规范

（一）响应码含义

|HTTP 状态码|含义|示例场景|

| —| —| —|

|200 OK|请求成功，服务器已成功处理请求并返回所需数据，客户端请求获取用户列表，服务器成功返回用户数据列表时，返回 200 状态码。|

|201 Created|资源已成功创建，在 POST 请求创建新资源成功后返回此状态码，例如创建新用户成功后返回 200 状态码和包含新用户信息的响应体。|

|204 No Content|请求成功，但服务器没有返回任何数据，通常用于更新操作成功后，例如更新用户信息成功，但没有新的数据需要返回给客户端时。|

|400 Bad Request|请求存在问题，服务器无法理解请求，可能是由于请求参数不合法、缺少必要参数等原因导致，客户端请求获取用户信息但未提供用户 ID，服务器将返回 400 状态码。|

|401 Unauthorized|用户未被授权访问请求的资源，当用户未提供有效的身份认证凭据或凭据过期时返回此状态码，用户尝试访问需要登录才能查看的页面但未登录时，服务器返回 401 状态码。|

|403 Forbidden|服务器理解请求，但拒绝执行该请求，通常是由于用户没有足够的权限访问资源，普通用户试图访问管理员专属的功能页面时，服务器返回 403 状态码。|

|404 Not Found|请求的资源未找到，客户端请求获取一个不存在的商品详情时，服务器返回 404 状态码。|

|500 Internal Server Error|服务器内部错误，服务器在处理请求过程中遇到了意外情况，这可能是由于服务器代码错误、数据库连接问题等原因导致，服务器在查询数据库时发生异常，无法正常返回数据时返回 500 状态码。|

（二）响应头规范

1、内容类型（Content-Type）：与请求头中的Content-Type类似，响应头中的Content-Type字段表明响应体的数据格式，常见的值为application/json、application/xml等，服务器应根据实际情况正确设置响应头的Content-Type字段，以便客户端正确解析响应数据。

|示例|说明|

|返回 JSON 格式的用户信息数据|Content-Type: application/json，客户端收到响应后，会根据此字段知道响应数据是 JSON 格式并进行相应的解析处理。|

2、缓存控制（Cache-Control）：用于控制响应数据的缓存行为，服务器可以在响应头中使用Cache-Control字段指定缓存策略，如是否允许缓存、缓存有效期等，常见的取值有public（公共缓存，任何缓存机制都可以缓存）、private（私有缓存，仅客户端缓存）、max-age（指定缓存的最大存活时间）等。

|示例|说明|

|希望客户端缓存响应数据 1 小时|Cache-Control: max-age=3600，客户端在收到此响应后的 1 小时内可以直接从缓存中读取数据而无需再次向服务器请求。|

（三）响应体规范

1、JSON 格式响应体

通用结构：一般情况下，响应体采用 JSON 格式时，整体结构为一个对象，包含以下常见字段：

code：状态码，用于表示业务逻辑层面的处理结果，一般使用整数表示，0 表示成功，非 0 表示不同的错误类型。

message，对请求结果的简要描述，例如成功时的提示信息或错误时的详细错误信息。

data：实际的业务数据，根据不同的接口功能返回相应的数据内容，如果是查询操作，可能返回查询到的记录列表；如果是创建或更新操作，可能返回新创建或更新后的记录信息等。

示例：

        {
            "code": 0,
            "message": "User information retrieved successfully.",
            "data": {
                "id": 1,
                "name": "John Doe",
                "email": "john.doe@example.com",
                "created_at": "2024-01-01T10:00:00Z"
            }
        }

2、XML 格式响应体：在一些特定场景下，可能需要使用 XML 格式的响应体，XML 格式的响应体具有更好的自描述性和扩展性，适用于复杂的数据结构和对数据格式要求较为严格的企业级应用，其结构根据具体的业务需求进行定义，但通常会包含根元素以及相应的子元素来表示不同的数据字段和层次关系。

示例：

        <response>
            <code>0</code>
            <message>User information retrieved successfully.</message>
            <data>
                <user>
                    <id>1</id>
                    <name>John Doe</name>
                    <email>john.doe@example.com</email>
                    <created_at>2024-01-01T10:00:00Z</created_at>
                </user>
            </data>
        </response>

四、错误处理与日志记录

（一）错误处理原则

1、友好性：向用户提供易于理解的错误信息，避免使用过于专业或晦涩的技术术语，错误信息应明确指出问题所在，并提供可能的解决方案或建议，当用户提交的数据格式不符合要求时，错误信息可以提示用户检查数据格式并在正确的地方进行修改。

2、一致性：在整个 API 中保持错误处理的一致性，无论是成功响应还是错误响应，都应遵循相同的结构和模式返回数据，这样可以使客户端更容易处理不同类型的响应结果。

3、分类处理：对不同类型的错误进行分类处理，例如客户端错误（如请求参数不合法、缺少必要参数等）和服务器端错误（如数据库连接失败、服务器内部异常等），针对不同类别的错误，可以采取不同的处理方式和返回相应的错误信息。

（二）错误码定义

除了上述提到的 HTTP 状态码外，还可以在业务层面定义更详细的错误码，以便客户端更准确地了解错误的具体原因，以下是一些常见的错误码示例：

错误码	错误描述	解决方案
1001	用户账号不存在	请检查输入的用户账号是否正确，若忘记账号可联系客服找回。
1002	密码错误	请重新输入密码，若忘记密码可使用密码找回功能重置密码。
1003	用户已被禁用	联系管理员了解账号被禁用原因并申请解封。
1004	无权限访问该资源	检查用户权限设置，确保拥有相应的访问权限，若需提升权限，请联系管理员进行授权操作。

（三）日志记录规范

1、：记录每个 API 请求的相关信息，包括请求时间、请求方法、请求 URL、请求头、请求体、响应码、响应头、响应体等，这些日志信息有助于后续的问题排查和性能分析，当服务器出现异常时，可以通过查看日志了解当时的请求情况和服务器的处理过程。

2、日志级别：根据事件的重要性和紧急程度划分不同的日志级别，常见的日志级别有 INFO（信息）、DEBUG（调试）、WARN（警告）、ERROR（错误）等，正常的请求处理过程可以记录为 INFO 级别的日志；当出现潜在问题但不影响系统正常运行时，记录为 WARN 级别；当出现严重错误导致系统无法正常工作时，记录为 ERROR 级别。

3、存储与管理：合理存储和管理日志文件，确保日志的安全性和可访问性，可以根据日志量的大小和系统的运行情况定期对日志进行备份和清理操作，为了方便查询和分析日志，可以建立索引或使用日志管理系统对日志进行分类和检索。

五、相关问题与解答

（一）为什么 API 接口开发要遵循接口开发规范？

保证接口的一致性和稳定性：遵循统一的规范可以使不同开发人员开发的接口在风格、结构和行为上保持一致，便于维护和管理，当多个团队共同开发一个大型项目的不同模块时，如果都按照相同的规范进行接口设计，那么各个模块之间的集成就会更加顺利，减少因接口差异导致的兼容性问题，规范的使用也有助于保持接口的稳定性，当系统进行升级或扩展时，只要遵循已有的规范，就能最大程度地减少对现有功能的影响。

提高开发效率：开发人员熟悉规范后，可以快速上手开发工作，减少学习成本和开发时间，在设计接口时，直接按照规范确定接口路径、请求参数和响应格式等，无需每次都重新思考和设计这些基本要素，在团队协作中，成员之间基于共同的规范进行沟通和开发，能够避免因理解不一致而产生的误解和重复工作，从而提高整个团队的开发效率。

便于接口的维护和扩展：规范的接口文档清晰明了，使得后续的维护人员能够快速理解接口的功能、使用方法和业务逻辑，当需要对接口进行修改或优化时，按照规范进行调整可以保证改动的合理性和兼容性，在添加新的功能或扩展现有接口时，遵循规范也能够使新接口与旧接口无缝衔接，方便用户使用和系统集成。

提升用户体验：对于使用 API 遵循规范的接口具有统一的操作方式和预期的响应结果，用户不需要花费额外的精力去适应不同风格的接口，降低了使用门槛和学习成本，规范的接口通常伴随着良好的错误处理和帮助文档，当用户遇到问题时能够快速定位和解决，提高了用户对 API 的满意度和使用体验。

（二）如何保证 API 接口的安全性？

身份认证与授权：采用合适的身份认证方式，如 API Key、OAuth、JWT 等，确保只有合法的用户能够访问接口，对不同的用户或应用授予不同的权限级别，严格控制对敏感数据的访问，在用户登录系统中使用 JWT 进行身份认证和授权，每次请求都携带有效的 token，服务器验证 token 的合法性后才允许访问相应的资源。

数据加密：在数据传输过程中使用加密技术，如 HTTPS 协议对传输的数据进行加密，防止数据在网络传输过程中被窃取或篡改，对于特别敏感的数据，还可以在存储时进行加密处理，银行系统的 API 在传输用户的账户信息和交易数据时必须使用 HTTPS 加密传输，以确保数据的安全性。

输入验证与过滤：对用户输入的数据进行严格的验证和过滤，防止 SQL 注入、XSS 攻击等常见的安全漏洞，在使用用户输入的数据进行数据库查询时，先对输入的数据进行合法性检查和转义处理，避免恶意代码的注入导致数据库安全问题，对上传的文件进行严格的格式和内容检查，防止恶意文件的上传和执行。

小伙伴们，上文介绍了“api接口开发规范”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。