一、API 基础概念与接口设计原则

说实话，干了这么多年开发，我见过太多因为接口没设计好而翻车的项目。有的团队把 API 当成“随便定义几个 URL”就完事，结果联调时鸡飞狗跳。我自己也踩过不少坑，后来才慢慢摸清门道。

这一章咱们先把地基打牢。说白了，API 就是系统之间的“对话规则”。你设计得好，两边聊得顺畅；设计得烂，整天吵架。

1.1 什么是 API？

API，全称 Application Programming Interface。翻译过来叫“应用程序编程接口”。听起来很唬人？其实就是个“中间人”。

它定义了：我给你什么数据，你返回什么格式，出错怎么办。就这么简单。

举个例子。你想查某个用户的资料。API 调用大概长这样：

GET /api/users/123
Accept: application/json

响应：
{
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2024-01-15T08:30:00Z"
}

嗯，这不就是用 HTTP 协议传了个 JSON 嘛。但就是这个小动作，能让前端、后端、第三方服务之间互通有无。

1.2 接口设计原则

我曾经接手过一个老系统，它的接口长这样：/getUserInfo?type=1&flag=true。你问我这些参数啥意思？没人知道。文档早丢了。这就是典型的设计失败案例。

好的接口设计，应该让人一眼看懂。下面这五个原则，是我这些年总结出来的铁律。

原则	说明	反例
资源导向	用名词表示资源，不要用动词	/getUsers 应改为 /users
HTTP 方法语义化	GET 查询，POST 创建，PUT 全量更新，DELETE 删除	用 POST /deleteUser 就是瞎搞
版本管理	API 必须有版本号，避免向前不兼容	直接改旧接口，害得调用方全崩
状态码规范	用 HTTP 状态码表达结果，别自己发明代码	不管成功失败都返回 200，靠 body 里的 code 区分
一致的命名风格	统一用下划线或驼峰，别混搭	既用 userName 又用 user_age

1.3 RESTful 风格入门

你想想看，为啥 RESTful 这么流行？因为它遵循了 Web 本身的设计哲学。每个资源都有唯一的 URL，操作通过 HTTP 方法表达。

举个例子，一个完整的用户管理 API 应该是这样的：

GET    /users          获取用户列表
POST   /users          创建新用户
GET    /users/{id}     获取单个用户
PUT    /users/{id}     全量更新用户
PATCH  /users/{id}     部分更新用户
DELETE /users/{id}     删除用户

是不是很清晰？URL 全是名词，方法全是标准动作。这就是 RESTful 的核心思想。

1.4 接口版本管理

版本管理这事，我吃过不少苦头。早期一个项目没有版本号，每次更新接口都要通知所有人，改完总有人忘了升级，系统直接崩。

常见的版本管理方式有这几种：

• URL 路径版本：/v1/users、/v2/users
• 请求头版本：Accept: application/vnd.myapp.v2+json
• 参数版本：/users?version=2

我个人最推荐第一种。虽然不太“优雅”，但是最直观、最容易调试。你想想看，后端出问题时，直接从 URL 就能看出来是哪个版本的接口，省得翻日志。

1.5 本章知识结构

下面这张图，概括了 API 接口设计的核心脉络。从“接口定义”出发，到“设计原则”，再到“质量属性”，最后落地到“具体实践”。你可以把它当作本章的思维导图。

1.6 高质量接口的共性

这些年看过的接口不下千个。好的接口都有几个共同点：

• 可读性强：URL 就是自文档，不需要额外查手册
• 容错性好：参数错了给明确提示，而不是抛个 500
• 幂等性：同样的请求重复发，结果应该一样
• 面向资源：把业务抽象成资源，而不是功能

说到幂等性，我举个例子。支付接口如果没有幂等性，用户点了一次“支付”，前端没响应，再点一次，结果扣了两次钱。这就是灾难。解决办法就是加一个“幂等键”，同样的键重复发，服务端直接返回之前的结果。