API¶

主要内容

API 是前后端契约；Cookie/Session/JWT/OAuth 解决登录和鉴权；CORS/CSRF 是浏览器安全相关重点；实时通信有短轮询、长轮询、SSE、WebSocket；文件系统要区分内容、元数据和权限。

参考文档¶

API 的制定.md、登录 & 鉴权.md、实时通信技术.md、websocket.md、文件处理与云存储.md、Axios.md

知识地图¶

概念：先理解这个模块为什么存在。
工具：再看它通过哪些工具落地。
场景：最后判断什么时候该用，什么时候不该用。

核心整理¶

API 是前后端契约；Cookie/Session/JWT/OAuth 解决登录和鉴权；CORS/CSRF 是浏览器安全相关重点；实时通信有短轮询、长轮询、SSE、WebSocket；文件系统要区分内容、元数据和权限。

我在整理这部分时的重点是把工具放回工程场景，而不是孤立记名词。一个工具出现，通常是为了解决某种复杂度：协作复杂度、上下文复杂度、运行环境复杂度、系统规模复杂度或信息获取复杂度。

学习笔记¶

先读 Why，确认它解决的问题。
再读 What，建立概念边界。
再读 How，补命令、API、配置和实践。
最后用一个小 demo 验证。

实践清单¶

用自己的话解释本模块核心概念。
找一个最小 demo 跑通。
记录一个踩坑点。
把相关命令或配置写成可复用片段。
回看飞书原文，补齐遗漏的术语。

飞书思考题¶

HTTP Code 和 JSON errCode 有什么区别？¶

HTTP Code 表示协议层状态，方便浏览器、网关和监控识别；JSON errCode 表示业务层状态，例如密码错误、余额不足、权限不足。

短轮询、长轮询、WebSocket、SSE 区别和场景？¶

短轮询简单但浪费；长轮询减少空请求；SSE 适合服务端单向推送；WebSocket 适合双向实时通信，如聊天和协作。

如何设计一个网盘？¶

需要用户、目录、文件元数据、对象存储 key、权限、分享链接、分片上传、断点续传、回收站、容量限制和下载鉴权。

API 设计细节¶

飞书 API 文档强调 URL、method、参数和返回格式。我的理解是：API 是前后端的合同，不清晰就会出现“前端以为这样传，后端以为那样收”。

一个接口至少写：

接口名
URL
Method
Headers
Query / Params / Body
Response
Error
Example

GET、POST 与特殊数据¶

GET 常用 query string 或 path param。POST 常用 JSON body。文件用 multipart/form-data，二进制或大文件不要硬塞 JSON。

时间一般用 ISO/RFC3339 字符串或 Unix timestamp。Base64 会增大体积，不适合大文件长期传输。

HttpOnly：降低 XSS 读取 cookie 的风险。
Secure：只通过 HTTPS 传输。
SameSite：限制跨站携带，降低 CSRF。
Domain/Path：控制作用范围。

CORS 的真实含义¶

CORS 不是服务器保护自己，而是浏览器限制网页脚本跨域读资源。服务器通过响应头告诉浏览器哪些来源、方法、头可以访问。

带 cookie 的跨域请求要同时满足：

服务端 Access-Control-Allow-Credentials: true。
Access-Control-Allow-Origin 不能是 *。
前端 fetch/axios 开启 credentials。
cookie 的 SameSite/Secure 设置允许。

登录与鉴权¶

登录是证明身份，鉴权是判断权限。

Session：服务端保存登录态，容易强制注销，分布式要共享存储。

JWT：token 自带声明和签名，服务端无状态校验，但强制注销和权限即时变更麻烦。

OAuth：第三方授权，用户通过授权中心给应用授权。

密码不能明文存储，要存加盐 hash。

实时通信展开¶

短轮询适合低频、简单状态。长轮询适合兼容性较好且数据不频繁。SSE 适合服务端持续推送，例如日志、通知、进度。WebSocket 适合双向实时，例如聊天室、协同编辑。

大规模实时系统不能只靠单进程内存广播，需要 Redis Pub/Sub、Stream 或消息队列。

文件存储¶

网盘或上传系统要拆分：

文件二进制内容：对象存储。
元数据：数据库。
权限：后端鉴权。
下载：签名 URL 或后端转发。

分片上传和断点续传适合大文件。

知识卡片¶

401 和 403¶

401 表示未认证，403 表示已认证但无权限。这两个状态不要混用。

CSRF 与 XSS¶

CSRF 利用浏览器自动带 cookie；XSS 是攻击者脚本在页面内执行。HttpOnly 可以降低 XSS 窃取 cookie 风险，但不能解决所有 XSS。

Signed URL¶

对象存储下载常用签名 URL。URL 有过期时间，可以避免文件永久公开。