什么是 API？写给非开发者店主的入门指南

您好，我是 yeonghyeon，负责 3Min API 的开发。

在上一篇数据库编里，我们收尾葡萄酒店店主的故事时，故意留下了一件事没讲。我当时说：线上商店开张以后，门店 POS、网站、合作餐厅带来的订单会自动堆到同一个数据库里 —— 但"自动"这两个字背后的那件工具，才是今天要讲的主角。它就是 API。

今天这篇文章只有一个目的。在深入学习"API"这个词背后的复杂技术之前，先建立起 "把自己业务的流向不是放在脑子里，而是整理成约定好的消息" 的感觉。只要这份感觉有了，剩下的东西在需要时会自然跟上。您不需要任何基础知识。

什么是 API

先从词典定义短短看一下。维基百科 把 API（Application Programming Interface）描述为"让应用程序之间可以相互交换功能或数据的约定"。

用一句话概括：

API = 让系统之间能够按照约定好的规则交换数据的窗口。

API 有多种方式，但今天在网络上使用最广的是 REST（或 RESTful）API。今天就以 REST 方式为基准来讲。REST 本身的技术细节不会深入展开。从业务的角度来说，只要有这样一个感觉就够用："向约定好的地址，发送约定好形状的消息，就会得到约定好形状的答复。"

这里需要提前点一下。API 总会对请求给出一个回答。这个回答先由一个区分成功或失败的数字给出定论，随后再带上详细的内容。订单有没有正确保存，或因为什么原因被拒绝——都装在这个回答里。具体长什么样，后面讲到葡萄酒店的故事时会再看一遍。

为什么需要"通道"

请想象一下银行。银行金库里放着所有客户的钱，但客户从来不会直接走进金库。取而代之的是柜台员工按照固定的表单（存取款单）接收请求，核对本人身份后再处理。就连柜台员工自己也不会随便进出金库，规则和权限都定得很清楚。

数据库也是同样的情况。从技术上讲，是可以通过互联网直接连上 DB 来读写数据的，但一旦把这扇门向所有人打开，生意就会崩塌。有人可以把整份客户名单原样带走，有人可以把商品价格改成 0 元，有人可以把库存表整张删掉。

正因如此，我们在数据库前面放一个 叫作 API 的窗口。外部发来的请求必须先过这个窗口。窗口要做三件事：校验（请求的格式对不对）、身份与权限确认（你是谁，能做什么），以及只执行约定范围内的动作（顾客只能查自己的订单，绝不能修改价格）。真正和外部世界接触的，是 API 而不是 DB。

葡萄酒店店主的 API

从上一篇的最后一幕接着讲。葡萄酒店店主开了线上商店，店内 POS、网站和合作餐厅同时看着同一个数据库。这幅画面能成立的唯一原因，就是它们都只通过 API 这条路才能碰到 DB。

把这三方发出的请求翻译成自然语言，大概长这样：

• 门店 POS → "请帮我保存一笔订单。"（新增写入）
• 线上商店 → "请告诉我 Alex 上个月买过哪些酒。"（读取）
• 合作餐厅 → "请把 Château Margaux 2020 的库存扣掉 10 瓶。"（修改）

每一个请求都走向约定好的地址（URL），包在约定好形状的消息里送过来。消息本身通常就是打包在 JSON 这种格式里的一块。如果 JSON 这个词对您来说还陌生，可以先去看看 Chae-won 之前写的 数据也值得一份计划。今天把它理解为"把一块数据按规格装起来送出去的信封"就够了。

把地址和消息形状事先对齐之后，店主在睡觉的时候订单也会自动进来，DB 里会按照同样的形状一条一条堆上去。门店员工不必手动抄写，线上商店的管理员也不用再拼 Excel。因为规则被建立起来，自动化才变得可能。

那么窗口收到请求之后会怎么样？一定会有回复。这个回复先由一个数字、而不是一句人话来定下结果。这个数字叫 HTTP 状态码，虽然有几十种，但业务负责人只要认得三大类就够了。

• 200 系 — 成功：请求被正常处理了。订单被保存了，或者您要查的数据跟着一起回来。（例如：200 OK、201 Created）
• 400 系 — 请求有问题：问题出在您发过去的消息上。必填字段缺了、没有权限、或者这个地址根本不存在。（例如：400 Bad Request、401 Unauthorized、404 Not Found）
• 500 系 — 服务器端出了问题：窗口里面自己坏了。就算您的请求没问题也可能失败，所以一般会设计成稍后重试。（例如：500 Internal Server Error）

这个数字后面通常还会跟着一块 JSON。成功的时候带的是保存下来的订单 ID，失败的时候带的是到底哪里错了、为什么错了。往葡萄酒店的 API 发一笔"少了 quantity 字段的订单"，窗口就会回一个 400，外加一条"quantity 字段必填"之类的消息。有了这个约定，不管是系统对系统，还是人对系统，都能用同一种语言区分成功和失败。

API 其实到处都是

就算不讲葡萄酒店的故事，您今天一整天用过的 App，大多数都在背后调着某家的 API。Instagram 那条动态流是服务器端的 DB 被 API 读出来的；特斯拉车主在手机 App 上看车况、天气 App 告诉您今天会下雨、外卖 App 展示餐厅菜单，全都是同一回事。最近连冰箱的下单按钮、汽车的语音助手、智能音箱，都是跑在 API 之上。

到目前为止讲的 API，都是"我需要的时候，走到对方窗口送出请求"这种方式。反过来，对方系统先找上我的窗口，告诉我"刚刚发生了这样的事"的方式也是需要的。支付完成的瞬间，支付公司把通知推到我的服务器，就是最典型的场景。这种方式另有其名，叫做 Webhook。

其实 API 和 Webhook 在技术上是完全一样的东西。请求的地址、消息的形状、认证方式、响应码——没有一个地方不同。它们是在同一个 HTTP 窗口上交换同一块 JSON 的同一个工具，连调用它们的代码都几乎分不出来。那为什么要用不同的名字？早期的 Web API 大多是为"我需要的时候去向对方要来"这种用法设计的。时间一长，"事情一发生，对方就先来告诉我"这种反方向的调用越来越多，为了区分这种反方向，大约在 2007 年前后才新起了 Webhook 这个名字。技术并没有一分为二，只是同一个工具上多了一个角色名而已。

所以只要这样记就够了：我先打过去叫 API，对方先打过来叫 Webhook。

那 API 具体怎么做

读到这里，您会很自然地想："那我也给我的生意做一个 API 不就行了？"然而真的要让一个 API"7×24 小时都安全地跑起来"，所需要的零件比想象中多得多。我坦白地列一下：

• 固定地址：必须能够从互联网上被调用，所以要买域名，配置 DNS，挂上 HTTPS 证书。
• 7×24 的在线服务器：哪怕只有一台宕机，营业就停。要部署多台服务器，监测故障，自动拉起。
• 代码：接收请求并校验、区分错误、按约定好的形状返回响应、把过程记录下来 —— 这些代码都要自己写。
• 身份与权限：必须分清楚谁能调用哪个 API。签发 API 密钥、让它过期、把被盗的密钥停用 —— 这是一项持续的运维工作。
• 数据库对接：DB 要单独安装和运行。备份、安全、性能调优都是和 API 并行的另一块。
• 弹性扩容和监控：活动期间流量飙升时要自动扩容，平时要缩减以节省成本。同时还要有实时盯住错误率、响应时间、成本的仪表盘。

这些零件并不需要完全靠一个人搭。AWS、Google Cloud、Cloudflare、Firebase、Supabase 这些云平台会分别提供其中的一些。但"选零件、拼零件、运营零件"这件事本身就是一个专业领域。让业务负责人从零开始搭，通常要花掉一位后端工程师几周到几个月的时间。

到这里的小结

把前面的内容简单串一下：

• API 是让您安全地访问数据库的窗口。
• 窗口只接受发往约定好的地址、按约定好形状组装的请求。
• 正因为有这一层约定，多个系统才能同时看着同一份数据一起运转。
• 您在睡觉的时候 API 一直在被调用，也在调用别家的 API。自动化的实体，就站在这些约定之上。

今天就能上手试的事

上一篇数据库编里，我们用三张 Excel 画出了业务的数据结构。今天来想象一下数据在其间来回流动的那条"通道"。只需要您的脑子加 AI，不需要写代码、不需要服务器、也不需要付费。

行动 1. 为您的业务画出一个端点

从上一篇分出来的"人 / 物 / 交易"三张表里挑一张，为它定义一个"会往这张表里新增一行的事件"。例如："线上商店收到一笔新订单的时候"。在纸上只写三行：

1. 事件名：例如 订单创建
2. 由谁发出：例如 线上商店、门店 POS、客户咨询表单
3. 带了哪些数据：例如 客户编号、商品编号、数量、金额

这三行，其实就是一个端点的设计稿。开发者在真正开始做 API 的时候，最先画的那张草图，也就是这种颗粒度的备忘录。

行动 2. 让 AI 给您一份整体方案

把行动 1 的那几行连同下面这段提示词一起，粘贴到 ChatGPT、Claude、Gemini 任意一个里。

请参考下面这份服务文档，告诉我，要把我刚才列出的端点真的实现出来，
应该按怎样的顺序开始，请用非开发者能听懂的语言一步一步讲。

https://3minapi.com/llms-full.txt

AI 通常给您的回答会沿着"建一个端点，把一笔订单当成一块 JSON 发过来"的方向。哪怕里面有些术语听着陌生，也不用慌张。您只要记住一件事：这件事就是在开我们今天讲的那一扇"窗口"。

行动 3. 3 分钟亲手试一次 API

真的去买域名、起服务器、装数据库的那条路，对今天这个阶段来说太重了。跟着下面这份快速入门指南走一遍，就可以在 3 分钟之内，用手走完建数据库 → 建 API 端点 → 调用 → 确认数据落进 DB 的全过程。

这里有个问题可能会冒出来：「API 建好了，可是数据库是什么时候建的？」前面说过，原本应该把 DB 单独安装和运营，但在 3Min API 里，只要您在创建端点时定义好要装哪些字段，配套的存储空间就会在背后一起建好。从店主的角度看，只要把窗口（API）设计好，金库（DB）就顺带准备好了。「3 分钟」之所以能写在名字里，原因就在这里。

👉 没有开发者也能创建端点 —— 快速入门指南

下一期

上一期看了装数据的容器，今天看了把这个容器和外部世界连起来的通道。走到这里，剩下的问题只有一个："在容器之间来回走的那些消息，到底长什么样？"

下一期我们要讲的就是那些消息的形状，也就是 JSON。请继续跟着葡萄酒店的一笔订单，看看它到底装进了哪个信封，从 POS 走到服务器、从服务器走到线上商店。

---

← 上一期：什么是数据库？Excel 用户的入门指南
→ 下一期：什么是 JSON？写给非开发者店主的入门指南