> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# HTTP、API、REST、认证、MCP 核心概念入门

> 写给: 有一点 programming 概念、但不写代码,每天要跟 engineer / vendor / 客户聊技术的人。
> 目标: 读完之后,任何技术对话不再 nodding-and-pretending,而且能拿一句话判断对方说得靠不靠谱。
> 怎么读: 全文用**一个餐厅点单系统**的类比贯穿到底。每节先讲"没它之前什么痛",再讲"它一句话是什么",最后给你"开会时可以这么说"。

***

## 怎么用这份文档

每个概念都按**同一个 4 段式**讲,你扫的时候认这个结构就行:

| 段         | 回答的问题                          |
| --------- | ------------------------------ |
| **痛**     | 没有它之前,哪里乱 / 慢 / 危险 / 做不大?      |
| **是什么**   | 一句话操作性定义(不堆术语)                 |
| **站在哪层**  | 它不是替代上一层,是在上一层之上加了什么           |
| **开会怎么说** | 一句能拿来判断 vendor / engineer 回答的话 |

记一句话当全文的骨架:

> **HTTP 是路;REST 是路上的交通规则;OpenAPI 是地图和合同;Auth 是门禁。**

类比帮你**理解**,这句抽象的话帮你**记住**。

***

## §1. 分层地图 — 一张图看懂全部

互联网上 99% 的事,本质都是**两台电脑在对话**:你开网页 = 你电脑跟网站服务器对话;POS 刷卡 = POS 终端跟支付公司服务器对话;AI 帮你下单 = AI 跟你的系统对话。

两台电脑要把这件事做好,得一层层往上盖楼。下面这张图是整份文档的地图——**先看懂这一张,后面每节都是在展开其中一层**:

```
┌─ AI 层 ────────────────────────────────────────────┐
│  Function Calling / Skill / MCP                     │  让 AI 替你调下面的能力
├─ 使用层 ────────────────────────────────────────────┤
│  SDK / CLI / 直接 HTTP                               │  人或程序怎么去用这些能力
├─ 语义层 ────────────────────────────────────────────┤
│  API → REST / GraphQL / gRPC                        │  系统对外开放哪些能力
│  + JSON(数据格式)+ OpenAPI(合同)+ Auth(门禁)    │  怎么描述、怎么管谁能用
├─ 传输层 ────────────────────────────────────────────┤
│  HTTP / HTTPS                                       │  消息怎么从 A 送到 B
└─────────────────────────────────────────────────────┘
            ▲ 每一层都站在下一层之上 ▲
```

**餐厅类比的全景**(后面每节展开一格):

| 层  | 概念        | 餐厅里是什么                 | 它补了下一层做不到的什么   |
| -- | --------- | ---------------------- | -------------- |
| 传输 | HTTP      | 传菜窗口,把话送进厨房            | 消息怎么送到         |
| 语义 | API       | 餐厅开放给客人的点单入口           | 外部能让系统做哪些事     |
| 语义 | REST      | 菜单按编号,只允许查 / 下 / 改 / 退 | 把乱喊变成可预测的规矩    |
| 语义 | OpenAPI   | 正式菜单 + 点单规则 + 字段说明     | 调用方怎么知道该怎么点    |
| 语义 | Auth      | 会员卡 / 员工证 / 桌号权限       | 谁能点、能点哪些       |
| 使用 | SDK / CLI | 点单 app / 服务员手持机        | 用熟悉的方式下单       |
| 异步 | Webhook   | 菜好了餐厅主动叫你              | 不用一直问"好了没"     |
| AI | MCP       | 菜单的英文版,外国人也能点          | 让任何 AI 标准化接你系统 |

***

## §2. HTTP — 消息怎么从 A 送到 B

**痛**: 你电脑想跟另一台服务器说话,但隔着整个互联网。没有一套大家都遵守的"怎么打电话、怎么写信封、怎么回话"的规矩,两台电脑根本对不上。

**是什么**: HTTP (HyperText Transfer Protocol,超文本传输协议) 是**两台电脑通过互联网说话最常用的一套规矩**。你浏览器打开任何网页都在用它。

**站在哪层**: 它是最底层的"路"。上面所有东西(API / REST / Auth)都跑在 HTTP 这条路上。

**餐厅类比**: HTTP 就是**传菜窗口 + 喊话的规矩**——客人(你电脑)隔着窗口跟厨房(服务器)喊话,喊的格式得统一,厨房才听得懂、回得了。

### 一次对话长什么样(看一眼就行,不用背)

你发出去的叫 **request**:

```
POST /api/orders HTTP/1.1                ← 这一行 = 动作 + 地址 + 协议版本
Host: api.example.com                    ← 发给谁
Authorization: Bearer abc123             ← 进门凭证(见 §5)
Content-Type: application/json           ← 我这封信里装的是 JSON

{"item": "炒饭", "qty": 2}                ← 真正的诉求
```

> 第一行那个 `HTTP/1.1` 不是独立的东西,它只是这行的版本标签,告诉对方"我用 HTTP 1.1 这套规矩说话"。新系统多用 `HTTP/2`,规矩内核一样,只是更快。

对方回的叫 **response**:

```
HTTP/1.1 201 Created                     ← 协议版本 + 状态码(201 = 创建成功)
Content-Type: application/json

{"order_id": 789, "status": "received"}  ← 回复内容
```

### HTTP 的 5 个动作(method)

| Method     | 一句话   | 餐厅里       |
| ---------- | ----- | --------- |
| **GET**    | 给我看一下 | 看菜单 / 查订单 |
| **POST**   | 新建一个  | 下一单       |
| **PUT**    | 整个换掉  | 整页菜单换新    |
| **PATCH**  | 改一下这里 | 单独改一个菜价   |
| **DELETE** | 扔掉    | 取消订单      |

### 状态码(response 第一行的数字)

| 范围      | 含义                                                    | 你该怎么反应      |
| ------- | ----------------------------------------------------- | ----------- |
| **2xx** | 成功(200 OK / 201 Created)                              | 正常          |
| **3xx** | 重定向(301 / 302)                                        | 地址搬家了,自动跳   |
| **4xx** | **你这边错**(400 / 401 没登录 / 403 没权限 / 404 找不到 / 429 太频繁) | 检查你的请求      |
| **5xx** | **对方那边错**(500 / 502 / 503)                            | 不是你的锅,服务器挂了 |

> 看到 404 别慌,是 URL 写错了。看到 500 不是你错,是对方服务器挂了。

### HTTPS = HTTP + 加密

把 HTTP 传的内容用 TLS 加密一遍,中间人看不到。**2026 所有 production API 都是 HTTPS**,看到 `http://`(没 s)就是测试环境或老系统。

**开会怎么说**: "这个接口走 HTTP 还是 HTTPS?生产环境必须 HTTPS。返回 4xx 是我们请求的问题,5xx 是你们服务端的问题。"

***

## §3. API / REST / GraphQL / gRPC — 系统对外开放哪些能力

### 先说 API:餐厅的"点单入口"

**痛**: 厨房(服务器)能做很多事,但客人不能冲进厨房自己炒菜。需要一个**受控的入口**,规定"你能让我做哪些事、怎么让我做"。

**是什么**: API (Application Programming Interface,应用程序编程接口) 是**一台电脑公开的"我能为你做这些事"的清单**。

**站在哪层**: API 是抽象概念,它要跑在 HTTP 这条路上(也可以跑别的路,但 99% 走 HTTP)。

**餐厅类比**: API = **菜单**。你按菜单点,厨房给你做,你不用懂厨房内部怎么运作。点一次菜 = 一次 API call。

一个 API 通常由这几样组成:

| 组成                      | 餐厅里           | 例子                                      |
| ----------------------- | ------------- | --------------------------------------- |
| **Endpoint(端点)**        | 餐厅地址 + 桌号     | `https://api.example.com/orders/123`    |
| **Method(动作)**          | 你想干啥          | GET 看 / POST 下单 / DELETE 取消             |
| **Request body(请求内容)**  | 你的诉求          | `{"item": "炒饭", "qty": 2}`              |
| **Response body(回复内容)** | 厨房回的          | `{"order_id": 789, "wait_minutes": 15}` |
| **Auth(鉴权)**            | 进门凭证          | 见 §5                                    |
| **Rate limit(限流)**      | "一桌每分钟限点 N 次" | 见 §7                                    |

> **关键澄清**: 很多人把 "API" 和 "REST API" 混着说。严格讲,API 是通用概念(任何"两台电脑的接口"都叫 API),REST 只是其中**一种风格**。日常说 "API" 通常默认指 REST(因为业内 80% 是),但它俩不是一回事。

### 再说 REST:为什么需要它

**痛**: 光有 HTTP,你可以**乱发**——`POST /doEverything`、`GET /deleteOrder`(用"看"的动作去删东西)。这些 HTTP 层面完全合法,服务器照样收,但乱到没法维护。需要一套规矩管住这种乱。

**是什么**: REST (REpresentational State Transfer) 是 2000 年提出的**用 HTTP 的设计风格**——**URL 指"东西"(名词),动作交给 HTTP method(动词)**。

**站在哪层**: **REST 不是新协议,不是 HTTP 的替代品**。它就是 HTTP,只是把 HTTP 用得有秩序。这是你今天最该记住的一点。

**餐厅类比**: REST = **一套点菜规矩**。菜单上印的是**菜名**(`/orders`,名词),不是"做炒饭""撤炒饭"(动词)。你要做什么,靠跟服务员说的**动作词**(POST = 点新的、DELETE = 退掉)。菜名不变,动作变。

#### 对比表 1:直接发 HTTP(raw HTTP) vs REST

这张表直接回答你的问题——"REST 和直接发 HTTP 到底差在哪":

| 维度             | 直接发 HTTP(raw,没规矩)                                 | REST(有规矩)                                             |
| -------------- | ------------------------------------------------- | ----------------------------------------------------- |
| **本质**         | HTTP 协议本身,啥都能发                                    | HTTP 之上的一套**约定**,不是新东西                                |
| **URL 长啥样**    | `/getOrder` `/createOrder` `/doEverything`(动词满天飞) | `/orders` `/orders/123`(全是名词)                         |
| **同一个东西的不同操作** | 每个操作发明一个新地址                                       | 地址同一个,换 method:`GET /orders/123` 查、`PUT` 改、`DELETE` 删 |
| **优点**         | 自由,想怎么发怎么发                                        | 可预测——看到 URL 就猜到怎么用                                    |
| **问题**         | 一个团队一套乱法,接手的人崩溃                                   | 要先约定好规矩(但业界已经约定俗成)                                    |
| **什么时候够用**     | 一次性脚本 / 内部小工具                                     | 任何要给别人用、要长期维护的 API                                    |

> 一句话: **raw HTTP 是"能沟通但格式随意",REST 是"把请求整理成人人都猜得到的固定套路"。**

REST 还有 6 条设计约束(stateless、cacheable 等),**你不用记**,知道"有这么个行规"就行。

### GraphQL 和 gRPC:另外两种风格(知道有就行)

不是所有 API 都是 REST。你可能听到这两个词,知道它们什么时候用即可。

#### 对比表 2:REST vs GraphQL vs gRPC

| 维度          | REST            | GraphQL                              | gRPC                            |
| ----------- | --------------- | ------------------------------------ | ------------------------------- |
| **餐厅类比**    | 标准套餐(1 号餐、2 号餐) | 自助餐(自己挑要哪几样)                         | 后厨内部传送带(极快,外人看不懂)               |
| **核心模型**    | 按资源 + 动作        | 你要哪些字段就拿哪些                           | 服务之间的二进制高速通信                    |
| **适合谁调**    | 对外公开 API        | 前端要灵活拿嵌套数据                           | 你自己的服务之间(不对外)                   |
| **代价**      | 拿一个字段也可能返回一整坨   | 权限和缓存很复杂,后端累                         | 调试难,像读二进制;浏览器不友好                |
| **普及度**     | \~80%,默认        | \~15%                                | \~5%,大多内部                       |
| **非工程师判断句** | "对外 API 默认就该是它" | "前端说要 GraphQL,问清楚是不是真有多客户端 / 嵌套数据需求" | "听到 gRPC,基本是内部服务通信,客户不会直接手写调用它" |

**开会怎么说**: "我们这个 API 是给外部客户调的,那就 REST + JSON,别上 gRPC——客户没法在浏览器里直接用。"

***

## §4. JSON 和 OpenAPI — 数据格式 与 合同

### JSON:数据长什么样

**痛**: 两台电脑传数据,得用一种双方都能读、又方便机器解析的格式。

**是什么**: JSON (JavaScript Object Notation) 是 2026 最通用的**结构化数据格式**。跟 API 打交道每天看它。

**餐厅类比**: JSON = **写在小票上的结构化订单**,谁拿到都能照着读。

长这样,看一眼就懂——就是"键: 值"+ 缩进:

```json
{
  "order_id": 789,
  "customer": "Alice",
  "items": [
    {"name": "炒饭", "qty": 2, "price": 12.50},
    {"name": "可乐", "qty": 1, "price": 2.50}
  ],
  "total": 27.50,
  "paid": true
}
```

它只有几种基本类型:文字 `"Alice"`、数字 `27.50`、是否 `true/false`、空 `null`、一组东西 `{...}`、一个列表 `[...]`。**看到 JSON 不慌,跟 Excel 一样直观。**

> 替代格式知道有就行:XML(老系统 / 银行)、YAML(配置文件)、Protobuf(gRPC 高性能场景)、CSV(导入导出 Excel)。2026 REST API 99% 用 JSON。

### OpenAPI:把 API 写成一份机器能读的合同

**痛**: 你有了一个 REST API,但**别人怎么知道它有哪些地址、每个收什么参数、回什么**?口头说 / 写个 Word 文档,机器读不了,也容易过期。

**是什么**: OpenAPI 是**一份描述你 REST API 长什么样的文件**(YAML 或 JSON 格式),业内标准是 OpenAPI 3.1。

**站在哪层**: 它是 API 的"说明书",但和普通文档的关键区别是——**机器能读**。机器能读,就能自动派生出一堆东西。

**餐厅类比**: 普通 API 文档 = 服务员口头给你介绍菜;OpenAPI = **正式印刷的菜单 + 点单规则 + 每道菜的配料份量说明**,标准格式,任何人(任何机器)拿到都能照着点。

#### 对比表 3:OpenAPI vs 普通 API 文档 vs SDK

这三个词容易混,这张表理清:

| 维度               | OpenAPI(合同)        | 普通 API 文档(网页) | SDK(代码库)         |
| ---------------- | ------------------ | ------------- | ---------------- |
| **是什么**          | 机器可读的规格文件          | 给人读的说明网页      | 给程序员的现成调用代码      |
| **给谁看**          | 机器(再由机器生成给人看的东西)   | 人             | 程序员              |
| **机器能读吗**        | ✅ 能                | ❌ 不能(纯给人看)    | ——               |
| **能自动生成什么**      | 文档网站、SDK、测试、mock   | ——            | ——               |
| **vendor 成熟度信号** | 有 OpenAPI = 专业、好对接 | 只有网页文档 = 一般   | 有官方多语言 SDK = 很成熟 |

#### 为什么 OpenAPI 重要:写一次,派生一切

有了这份合同文件,下游全自动:

| 能自动生成                | 工具例子                      |
| -------------------- | ------------------------- |
| **好看的文档网站**          | Swagger UI、ReDoc、Scalar   |
| **多语言 SDK**          | OpenAPI Generator(50+ 语言) |
| **测试 / mock server** | Prism、Postman             |
| **API 网关配置**         | AWS API Gateway 直接 import |

> 这就是为什么 Stripe / GitHub / OpenAI 的多语言 SDK 不是人手写七遍——是从一份 OpenAPI 合同**自动生成**的。**2026 没 OpenAPI = 业内非标**。

#### OpenAPI 是自动生成的吗?——按你的栈对号入座

这是高频疑问:"装个 framework 就自动有 OpenAPI 文档吗?" 答案分两类:

| 你的栈                                           | OpenAPI 文档怎么来         | 你要做什么                                          |
| --------------------------------------------- | --------------------- | ---------------------------------------------- |
| **Python / FastAPI**                          | **完全内置**,自动           | 啥都不装,跑起来访问 `/docs` 就有交互文档                      |
| **Node / Hono**(edge / Cloudflare Workers 首选) | 官方中间件,靠 Zod schema 生成 | 装 `@hono/zod-openapi` + `zod`,同一份 Zod 既校验又生成文档 |
| **Node / NestJS**                             | 官方模块,接近内置             | 装 `@nestjs/swagger`,加注解                        |
| **Node / Fastify**                            | 官方插件                  | 装 `@fastify/swagger` + `@fastify/swagger-ui`   |
| **Node / Express**                            | 社区插件                  | 装 `swagger-ui-express`,手动或注解生成                 |
| **Java / Spring Boot**                        | 社区标准库                 | 加 `springdoc-openapi` 依赖,自动扫描                  |
| **.NET / ASP.NET Core**                       | 新版模板默认带               | 模板自带,或加 `Swashbuckle`                          |
| **Go**                                        | 注解工具                  | 用 `swaggo/swag` 扫注释生成                          |

> 共同套路: **你写代码 + 标注类型 → 工具读你的标注 → 自动吐出 OpenAPI 合同 → 再渲染成文档网站**。差别只在"自带 vs 装个包"。FastAPI 是自带得最彻底的,这也是它最大卖点之一。

**开会怎么说**: "你们 API 有 OpenAPI spec 吗?有的话给我那个 `openapi.json`,我们这边能自动生成对接代码,省得手写。"

***

## §5. Auth — 谁能进、能做什么

这是你卡得最深的一节,单独讲透。

### 先分清两个词

**痛**: 任何系统都不能让"是个人就能调、想干啥干啥"。得回答两个问题:你是谁?你能干什么?

**是什么**: Auth = **Authentication(认证:你是谁)** + **Authorization(授权:你能干什么)**。两个词都缩写成 auth,但不是一回事。

**餐厅类比**: Authentication = 看你的**会员卡/员工证**(确认你是谁);Authorization = 看你的**桌号权限/职位**(普通顾客不能进后厨,服务员不能改菜价)。

> 记住一个反常识的事实: **大多数 auth 麻烦不是"登录按钮做不出来",而是 organization、role、SSO、员工离职注销、session、审计日志——这些后面越拖越长。** 这就是为什么 auth 是个大坑。

### B2C vs B2B:这就是 "WorkOS B2B 专精" 的含义

这直接回答你的问题"什么叫 B2B 专精":

|            | B2C(卖给个人)        | B2B(卖给企业)                                         |
| ---------- | ---------------- | ------------------------------------------------- |
| **一个用户代表** | 他自己              | 通常属于**一个公司(organization)**                        |
| **要管什么**   | 登录、密码、改资料        | 还要管:谁属于哪个公司、谁是 admin、role、团队、**用公司账号登录**、员工离职自动封号 |
| **登录方式**   | 邮箱密码 / Google 登录 | 还要支持**企业 SSO**(用公司的 Okta / 微软账号登)                 |

> **B2B auth 不只是 login,它要管整个"公司 + 员工"的身份生命周期。** 这就是为什么有 WorkOS 这种"B2B 专精"的产品——它把 B2B 才需要的那一堆复杂东西(SSO、目录同步、审计)替你做好了。

### 三个缩写一次讲清(你问的 SSO / SAML / SCIM)

| 缩写       | 全称                                          | 一句话                                                                 | 餐厅类比                  |
| -------- | ------------------------------------------- | ------------------------------------------------------------------- | --------------------- |
| **SSO**  | Single Sign-On(单点登录)                        | 员工**用公司账号**(Okta / 微软 Entra ID / Google Workspace)登录你的 app,不用另记一套密码 | 公司一卡通,刷它就能进所有门        |
| **SAML** | Security Assertion Markup Language          | 企业 SSO 常用的**老牌协议**。重点不是它优雅,是**大公司 IT 部门只认它**                        | 一种全行业通用的"护照"格式        |
| **SCIM** | System for Cross-domain Identity Management | 公司 HR/IT 系统**自动同步名单**给你的 app:入职自动开账号,离职自动封号                         | 公司前台自动把"谁入职谁离职"通知到各部门 |

记住这一句锚:

> **SAML 解决"怎么登录";SCIM 解决"员工进出怎么同步"。**

### AWS Cognito 到底麻烦在哪

你的原话——"Cognito 麻烦在什么地方我没太理解"。不写"UX 烂"这种空话,拆成**可验证的具体痛点**:

| 痛点                 | 具体是什么                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **配置概念多、路径绕**      | Cognito 很 AWS-native,User Pool / Identity Pool / Federation 一堆概念,配置入口分散,初次上手要理解不少 AWS 自己的抽象          |
| **要写不少 glue code** | 能做到的事大多能做,但常常需要更多胶水代码 + 理解 AWS 配置才跑得通,不如 Clerk/WorkOS 开箱顺滑                                           |
| **hosted UI 定制受限** | 如果你要一个非常 polished 的注册/登录/组织管理界面,Cognito 自带的界面定制能力有限,往往得自己补体验                                         |
| **B2B 组织模型不自然**    | 它能接 SAML/OIDC,但 "organization、member、role、企业自助开通、SCIM 流程" 这套 B2B 抽象,不如 B2B-first 的产品(WorkOS/Clerk)直观 |

> **但 Cognito 不是不能用**: 如果你团队重度在 AWS、成本敏感、工程能力强,Cognito 仍是合理选择。它的麻烦是"DX(开发体验)和 B2B 抽象不够顺",不是"做不到"。

### 4 种 auth 方式(凭证长啥样)

| 方式                    | 餐厅类比           | 长什么样                                   | 何时用                         |
| --------------------- | -------------- | -------------------------------------- | --------------------------- |
| **API Key**           | 公司门禁卡(一张卡通所有门) | `Authorization: Bearer sk_live_abc123` | 简单 / 服务器之间 / Stripe SDK 用这个 |
| **Bearer Token(JWT)** | 短期访客证          | `Authorization: Bearer eyJhbG...`      | 登录后 web/手机 app 调 API        |
| **OAuth 2.1**         | 用第三方账号登录       | "用 Google/GitHub 登录"那套跳转               | 跨公司集成                       |
| **SSO(SAML / OIDC)**  | 公司一卡通          | 走企业 IdP(Okta / 微软 / Google)            | 企业客户内部                      |

> JWT(那串 `eyJhbG...`)其实是一段编码后的 JSON,解码出来自带"我是谁 + 我能干什么 + 过期时间",服务器验个签就能用,不用每次查数据库。内部结构见附录。

### 对比表 4:2026 auth 选型(Cognito vs Clerk vs WorkOS vs Supabase Auth)

经 web search + Codex 二次核对官方定位:

| 维度               | AWS Cognito | Clerk              | WorkOS         | Supabase Auth     |
| ---------------- | ----------- | ------------------ | -------------- | ----------------- |
| **最佳场景**         | 重度 AWS 团队   | 早期 B2B/B2C 想快上线    | 已有 auth、只缺企业功能 | 已用 Supabase 做数据库  |
| **B2C / B2B 强项** | 都一般         | B2C 丝滑 + 有 B2B org | **B2B 专精**     | 跟数据库强绑定           |
| **SSO / SAML**   | 能做但绕        | 支持                 | **最强**         | 支持                |
| **SCIM / 目录同步**  | 有但不直观       | 支持                 | **最强**         | 较弱                |
| **UI / 界面成本**    | 高(要自己补)     | **最低(预制组件)**       | 中(B2B 专精)      | 中(要自己搭)           |
| **vendor 锁定**    | 锁 AWS       | 中                  | 中              | 锁 Supabase        |
| **2026 建议**      | 重度 AWS 才选   | 想快、要好看 → 选它        | 客户要 SSO → 选它   | 全栈在 Supabase → 选它 |

**给你(从 Cognito 来)的判断**:

- 痛点是 **Cognito 太难用、想要好 DX、产品偏 B2C/快速迭代** → 转 **Clerk**。
- 痛点是 **要卖给大企业、客户开口就要 SSO** → Cognito 很吃力,**WorkOS** 就是为这个生的。
- **重度绑在 AWS、auth 又不是瓶颈** → 留在 Cognito 也合理,不要为换而换。

> 业界最常见路径: **先上 Clerk 求快 → 涨到约 5 万 MAU(Monthly Active Users,月活用户)撞到成本线 → 迁到 Supabase Auth 或 Better Auth 控成本。** 还有组合拳:Supabase 管数据库 + 应用层登录,WorkOS 单独接企业 SSO。

**开会怎么说**: "我们客户里有要 SSO 的吗?有的话 Cognito 会很痛,该考虑 WorkOS。SAML 管登录、SCIM 管员工进出,这两个企业客户一定会问。"

***

## §6. SDK / CLI / 直接 HTTP — 三种用 API 的方式

**痛**: 你知道一个 API 存在了,但**具体怎么调它**?直接拼 HTTP 请求太原始,每次都要自己处理认证、格式、错误。

**是什么**: 同一个 API,有三种用法,从原始到方便:

- **直接 HTTP** = 自己拨号 + 自己背菜单(最原始)
- **SDK**(Software Development Kit)= 一个写好的"点单助手"代码库,程序员写一行就调上
- **CLI**(Command Line Interface)= 命令行工具,人或脚本敲命令就能用

**餐厅类比**: 直接 HTTP = 自己打电话报菜名;SDK = 餐厅给你的**点单 app**(程序员用);CLI = 服务员的**手持点单机**(运维 / 你 / AI 用)。

### 同一件事(拿订单 123),三种写法

直接 HTTP(最底层,任何语言都行):

```
GET https://api.example.com/orders/123
Authorization: Bearer abc123
```

SDK(各语言不同,这里只看"感觉",不用懂语法):

| 栈         | 长什么样                                |
| --------- | ----------------------------------- |
| Python    | `client.orders.get(123)`            |
| Node / TS | `await client.orders.get(123)`      |
| Java      | `client.orders().get(123)`          |
| .NET      | `await client.Orders.GetAsync(123)` |
| Go        | `client.Orders.Get(ctx, 123)`       |

CLI(跟语言无关):

```
example-cli orders get 123
```

### 对比表 5:SDK vs CLI vs 直接 HTTP

| 维度        | 直接 HTTP      | SDK              | CLI                   |
| --------- | ------------ | ---------------- | --------------------- |
| **使用者**   | 任何人          | 程序员              | 运维 / 用户 / **AI**      |
| **上手成本**  | 低(但啥都自己处理)   | 中(要会那门语言)        | 低(敲命令)                |
| **能自动化吗** | 能但麻烦         | 能(写进 app)        | **最适合**(Unix 管道 / 脚本) |
| **适合场景**  | 一次性测试 / curl | 写一个持续调 API 的 app | shell 脚本 / 让 AI 帮你跑   |

### 业界成熟 SaaS 通常三个都给

| SaaS           | API            | SDK       | CLI        |
| -------------- | -------------- | --------- | ---------- |
| **GitHub**     | REST + GraphQL | 多语言官方 SDK | `gh`       |
| **Stripe**     | REST           | 8+ 语言 SDK | `stripe`   |
| **Cloudflare** | REST           | TS SDK    | `wrangler` |
| **Vercel**     | REST           | Node SDK  | `vercel`   |

> **2026 标准**: 同一个后端 REST API,上面再包 SDK(给开发者)+ CLI(给运维 / AI)。三层都是薄包装,核心还是那个 API。CLI 用哪个 framework、怎么打包成单文件,见附录。

**开会怎么说**: "你们有官方 SDK 和 CLI 吗?有 CLI 的话我们能直接让 AI agent 调,不用写代码。"

***

## §7. Webhook 和 Rate Limiting — 异步通知 与 防滥用

### Webhook:服务器反过来找你

**痛**: 调 API 是**你主动找服务器**。但有些事是"等出结果"——支付有没有成功、AI 接完电话没有。你总不能每秒去问一次"好了没"。

**是什么**: Webhook 是**反过来——服务器有事了主动推给你**(事件触发)。

**餐厅类比**: Webhook = **餐厅的取餐器**。点完餐你不用反复跑去问"好了没",做好了取餐器一震——那个震动就是 webhook。

流程:你先告诉对方"出事了发到我这个 URL" → 某事发生 → 对方 POST 到你的 URL → 你处理。

典型场景:

| Webhook 触发于 | 你收到要做什么             |
| ----------- | ------------------- |
| 支付成功        | 在数据库标记订单已付 + 给客户发邮件 |
| AI 接完电话下单   | 在 POS 写入订单          |
| 用户注册        | 同步到 CRM             |

> 工程上 webhook 有几个坑(防伪造签名、同一事件可能被重发要能去重、对方挂了要重试),这些是 engineer 实现细节,你知道"有这些考量"即可,细节见附录。给客户发 webhook 的业界工具:Svix(默认)、Hookdeck、AWS EventBridge。

### Rate Limiting:限流

**痛**: 不限制的话,一个客户(或一段失控的代码)可以每秒打你几千次,把系统打爆,也对其他客户不公平。

**是什么**: 限制**单个客户单位时间能调多少次**。

**餐厅类比**: "今日特价每人限购 2 份"。

你被限流时,服务器返回 **HTTP 429(Too Many Requests)**,并在响应头告诉你上限多少、还剩几次、什么时候重置。你按那个时间等就行。

> 限流有几种算法(固定窗口 / 滑动窗口 / 令牌桶 / 漏桶),**你不用懂**,知道"看到 429 = 调太快了,等一下"就够。算法细节见附录。

**开会怎么说**: "你们 API 的 rate limit 是多少?我们高峰期会不会撞到 429?撞到的话有没有 retry 机制?"

***

## §8. AI 层 — 让 AI 替你调上面这一切

前面 7 节讲完,你的系统已经能跟别的系统对话了。最后一层:**怎么让 AI 替你操作这些能力**。三个词,场景不同。

### LLM Function Calling:AI 调你自己后端的代码

**是什么**: 你在自己后端代码里告诉 AI "我有这几个函数可以调"(查订单、改菜单、查会员),AI 决定何时调哪个,你的代码执行后把结果给 AI。

**餐厅类比**: 你雇了个智能秘书(AI),告诉她"桌上有 5 个按钮",你说话,她决定按哪个 + 看结果 + 回答你。

**何时用**: 客户在**你自己的 SaaS dashboard** 里用 AI 助手。

### Anthropic Skill:教 AI 怎么用你的 CLI

**是什么**: 一份小的 markdown 文件,教 AI "在你公司怎么用某个 CLI / 工具的特殊用法"。

**餐厅类比**: 给新员工的"如何用咖啡机"便利贴——咖啡机本来就在,新员工大体会用,便利贴只补"我们公司默认 oat milk + double shot"。

**何时用**: 你**内部团队**让 Claude 帮忙跑活。

### MCP:让外部任何 AI 标准化接你系统

**是什么**: MCP (Model Context Protocol) 是 Anthropic 2024 年底推出的**开放协议**,让任何品牌的 AI(Claude / Cursor / ChatGPT)都能通过一套标准协议调用你的工具。

**餐厅类比**: MCP = **菜单的英文版**。任何外国客人(任何品牌的 AI)都能照这本标准英文菜单点菜,不需要懂你餐厅特有的中文菜单格式(你私有的 REST API)。

**站在哪层**: **MCP 不替代你的 REST API,是 REST API 之上的一个协议层**——它收到 AI 的调用,翻译成对你普通 REST API 的请求。

**何时用**: 客户问"我能在 ChatGPT / Cursor 里接你的 SaaS 吗?" 这时才建,没人问就别建(浪费)。

### 三个怎么选

|            | Function Calling  | Skill          | MCP            |
| ---------- | ----------------- | -------------- | -------------- |
| **AI 的角色** | 你 app 内的助手        | 帮你跑 CLI 的助手    | 外部 AI 接你系统     |
| **给谁**     | 你 SaaS 的客户(在你界面内) | 你内部开发团队        | 外部 AI client   |
| **开发难度**   | 中(写函数声明)          | 低(写个 markdown) | 高(部署一个 server) |
| **一句话**    | AI 调我后端函数         | AI 学会用我的 CLI   | 任何 AI 标准化接我系统  |

> 深入决策(什么时候该建 MCP、自建 vs hosted、成本)见 [mcp-vs-cli-vs-skills-2026.md](/ai/product/mcp-vs-cli-vs-skills-2026.md)。MCP 现状:热度高但约一半公开 server 已废弃,真正用赢的是 GitHub / Linear / Stripe 把它当产品卖。

**开会怎么说**: "客户是在我们界面里用 AI(那是 Function Calling),还是想在他们自己的 ChatGPT 里接我们(那才需要 MCP)?这俩是两回事。"

***

## §9. 一张表回顾全部

| 层   | 概念               | 餐厅类比         | 一句话                   |
| --- | ---------------- | ------------ | --------------------- |
| 传输  | HTTP / HTTPS     | 传菜窗口         | 消息怎么送到,HTTPS = 加密版    |
| 格式  | JSON             | 结构化小票        | API 数据长这样             |
| 接口  | API              | 菜单           | 系统对外开放的能力清单           |
| 风格  | REST             | 点菜规矩         | HTTP 之上的秩序,80% API 是它 |
| 风格  | GraphQL / gRPC   | 自助餐 / 内部传送带  | 灵活拿数据 / 内部高速通信        |
| 合同  | OpenAPI          | 正式菜单         | 机器可读规格,自动生成 SDK/文档    |
| 门禁  | Auth             | 会员卡 + 桌号权限   | 你是谁 + 你能干什么           |
| 使用  | SDK / CLI        | 点单 app / 手持机 | 给开发者 / 给运维和 AI        |
| 异步  | Webhook          | 取餐器          | 服务器反过来找你              |
| 防滥用 | Rate Limit       | 每人限购 2 份     | 限频率,429 = 太快了         |
| AI  | Function Calling | 智能秘书按按钮      | 客户在你界面内用 AI           |
| AI  | Skill            | 咖啡机便利贴       | 内部团队让 AI 用 CLI        |
| AI  | MCP              | 菜单英文版        | 外部任何 AI 接你系统          |

***

## §10. 我该重点看哪些?(按角色)

**完全不懂的 PM / 老板**: §1 + §2 + §3(到 REST 为止)+ §5 Auth + §9 那张表。约 10 分钟,听到别的词不慌。

**Advisor / Fractional CTO(你)**: 全文一遍。重点 §3 REST + §4 OpenAPI + §5 Auth + §8 AI 三件套。GraphQL/gRPC、附录知道有即可。

**给客户解释 "我们 SaaS 怎么 work"**: 用 §1 的分层图当白板;重点讲 §8——客户的 AI 怎么接你(Function Calling vs MCP 是两回事)。

***

## 附录 — engineer 才需要的细节(可跳过)

> 主线已经够你聊天用了。下面是真要深入实现时才碰的东西,不影响理解全局。

### A1. JWT 内部结构

JWT 由三段用 `.` 隔开:**Header**(用什么算法)+ **Payload**(`user_id` / `role` / `exp` 过期时间等)+ **Signature**(防篡改的签名)。服务器用密钥验签名,签名对就信任 payload,不用查数据库。

### A2. Rate Limit 四种算法

固定窗口(每分钟 60 次,简单但边界会突刺)、滑动窗口(更平滑)、令牌桶(平时攒令牌,允许突发)、漏桶(严格匀速)。响应头通用三件套:`X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`。

### A3. CLI framework 与单文件打包

| 栈         | CLI framework      | 打包成单文件                            |
| --------- | ------------------ | --------------------------------- |
| Python    | Typer / Click      | PyInstaller / Nuitka              |
| Node / TS | oclif / Commander  | pkg / ncc                         |
| Java      | picocli            | GraalVM native-image              |
| .NET      | System.CommandLine | `dotnet publish --self-contained` |
| Go        | Cobra              | `go build`(天然单文件,Go 的强项)          |
| Rust      | clap               | `cargo build --release`           |

> Go / Rust 在 CLI 领域占主导,因为天然单文件 + 启动快。`gh` / `kubectl` / `terraform` 都是 Go 写的。

### A4. REST API server framework(按语言)

| 栈         | 主流 framework                      | 2026 新项目推荐                                                         |
| --------- | --------------------------------- | ------------------------------------------------------------------ |
| Python    | FastAPI / Flask / Django REST     | FastAPI                                                            |
| Node / TS | Hono / Fastify / Express / NestJS | **edge/Cloudflare Workers → Hono**;传统服务器 → Fastify(新)或 NestJS(企业级) |
| Java      | Spring Boot / Quarkus             | Spring Boot                                                        |
| .NET      | ASP.NET Core                      | ASP.NET Core Minimal APIs                                          |
| Go        | Gin / Fiber / Echo                | Gin                                                                |
| Rust      | Axum / Actix                      | Axum                                                               |

### A5. OAuth / SAML / MCP transport 等深水区

OAuth 的 grant types(authorization code / client credentials 等)、SAML 的 XML assertion 流程、MCP 的 transport(stdio / SSE / streamable HTTP)、Webhook 签名验证(HMAC)实现——这些都是 engineer 实现时才查的,需要时单独深入,或见 related playbooks。

***

## §11. Sources

### Standards & Specs

- [HTTP/1.1 RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110)
- [JSON RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259)
- [REST 原论文 (Roy Fielding 2000)](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)
- [OAuth 2.1 Draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/)
- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)

### Tools & frameworks

- API server: [Hono](https://hono.dev/)(edge / Cloudflare Workers), [FastAPI](https://fastapi.tiangolo.com/), [Fastify](https://fastify.dev/), [Spring Boot](https://spring.io/projects/spring-boot), [ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/), [Gin](https://gin-gonic.com/)
- OpenAPI 自动生成: [FastAPI Features](https://fastapi.tiangolo.com/features/), [@hono/zod-openapi](https://hono.dev/examples/zod-openapi), [@fastify/swagger](https://github.com/fastify/fastify-swagger), [OpenAPI Generator](https://openapi-generator.tech/)
- Auth: [AWS Cognito](https://docs.aws.amazon.com/cognito/), [Clerk](https://clerk.com/), [WorkOS](https://workos.com/), [Supabase Auth](https://supabase.com/docs/guides/auth)
- Auth 选型对比(2026): [Clerk vs Auth0 vs Supabase vs WorkOS](https://gautamkhorana.com/blog/authentication-services-2026-clerk-auth0-supabase-workos/)
- Webhook: [Svix](https://www.svix.com/), [Hookdeck](https://hookdeck.com/)
- AI 层: [Anthropic Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use), [Anthropic Skills](https://platform.claude.com/docs/en/build-with-claude/skills-guide), [Model Context Protocol](https://modelcontextprotocol.io/)

### Related playbooks

- [mcp-vs-cli-vs-skills-2026.md](/ai/product/mcp-vs-cli-vs-skills-2026.md) — 决策框架
- [build-cli-with-skills-2026.md](/ai/product/build-cli-with-skills-2026.md) — 具体 tutorial
- [mcp-platforms-vs-build-yourself.md](/ai/product/mcp-platforms-vs-build-yourself.md) — MCP 高阶决策