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

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

#怎么用这份文档

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

记一句话当全文的骨架:

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
└─────────────────────────────────────────────────────┘
            ▲ 每一层都站在下一层之上 ▲

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

#§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)

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

看到 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 通常由这几样组成:

关键澄清: 很多人把 "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 到底差在哪":

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

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

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

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

#对比表 2:REST vs GraphQL vs gRPC

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

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

#JSON:数据长什么样

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

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

餐厅类比: 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 重要:写一次,派生一切

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

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

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

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

共同套路: 你写代码 + 标注类型 → 工具读你的标注 → 自动吐出 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 专精":

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

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

记住这一句锚:

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

#AWS Cognito 到底麻烦在哪

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

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

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

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

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

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

给你(从 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(各语言不同,这里只看"感觉",不用懂语法):

CLI(跟语言无关):

example-cli orders get 123

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

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

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 有几个坑(防伪造签名、同一事件可能被重发要能去重、对方挂了要重试),这些是 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 吗?" 这时才建,没人问就别建(浪费)。

#三个怎么选

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

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

#§9. 一张表回顾全部

#§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 与单文件打包

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

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

#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
• JSON RFC 8259
• REST 原论文 (Roy Fielding 2000)
• OpenAPI 3.1 Specification
• OAuth 2.1 Draft
• MCP Specification

#Tools & frameworks

• API server: Hono(edge / Cloudflare Workers), FastAPI, Fastify, Spring Boot, ASP.NET Core, Gin
• OpenAPI 自动生成: FastAPI Features, @hono/zod-openapi, @fastify/swagger, OpenAPI Generator
• Auth: AWS Cognito, Clerk, WorkOS, Supabase Auth
• Auth 选型对比(2026): Clerk vs Auth0 vs Supabase vs WorkOS
• Webhook: Svix, Hookdeck
• AI 层: Anthropic Tool Use, Anthropic Skills, Model Context Protocol

#Related playbooks

• mcp-vs-cli-vs-skills-2026.md — 决策框架
• build-cli-with-skills-2026.md — 具体 tutorial
• mcp-platforms-vs-build-yourself.md — MCP 高阶决策