网页api接口

打开浏览器控制台，网页输入 fetch('/api/user')，网页按下回车。网页两秒后你拿到一段 JSON。网页这个过程背后跑的网页就是网页 API 接口——一套让前端页面跟服务器交换数据的约定。

没有它，网页你每次点“加载更多”都得刷新整个页面。网页有了它，网页页面只取需要的网页那一小块数据，剩下的网页部分纹丝不动。

一个典型的网页网页 API 接口就是一条 URL，加上请求方法和返回格式。网页比如：

GET https://example.com/api/articles?网页page=2&limit=10

服务器收到这个请求，返回类似这样的网页东西：

{  "code": 0, "data": [ {  "id": 11, "title": "第一篇" }, {  "id": 12, "title": "第二篇" } ], "total": 87 }

前端拿到 data 数组，渲染成列表。网页就这么简单。但“简单”是表面上的。

大多数人接触的第一个 API 风格是 REST。用 GET 取数据，POST 创建，PUT 更新，DELETE 删除。资源用 URL 表示，操作靠 HTTP 方法区分。

这套约定流行了十几年，好处是直观。坏处也有——当一个页面需要同时拿用户信息、订单列表和消息未读数时，你得发三个请求。移动端网络稍微差一点，用户就盯着白屏等。

于是 GraphQL 出来了。一个 POST 请求，body 里写清楚你要哪些字段，服务器一次性返回。听起来很美。实际用起来，缓存变复杂了，查询性能不可控，前端写 query 的复杂度也不低。我见过不少团队从 REST 迁到 GraphQL，半年后又迁回去一部分。

还有 gRPC-Web，用 protobuf 做序列化，性能好，但浏览器支持一直是个坎。除非你的项目对传输效率极度敏感，否则没必要上来就选它。

很多后端开发者喜欢所有接口都返回 200，然后在 body 里写 { "code": 500, "msg": "服务器错误"}。这种做法让 HTTP 状态码形同虚设。

正确的做法是：资源找不到就返回 404，参数校验失败就返回 422，没登录就返回 401，没权限就返回 403。前端拦截器根据状态码做统一处理，业务代码里不用再判断 code 字段。

我见过一个项目，接口返回 200 但 body 里 code 是 401，结果前端拦截器只认 HTTP 状态码，token 过期了页面还在那儿傻等着。这种坑踩一次就够了。

接口一旦发布，就有外部调用方依赖它。你改了字段名，对方系统就崩了。所以从第一天起就要考虑版本。

常见做法是把版本号放进 URL：/api/v1/users。也有放在 Header 里的：Accept: application/vnd.myapp.v2+json。前者直观，后者更符合 REST 理念。选哪个都行，关键是别等到出事了才想起来。

我个人的偏好是 URL 版本。调试方便，日志里一眼能看出来，不用去翻 Header。丑陋一点，但实用。

写完接口不写文档，等于没写。Swagger（现在叫 OpenAPI）是标配了，定义好 schema，自动生成交互式文档。前端不用追着你问字段含义，测试也能直接在上面发请求。

有时候排查问题，我会直接在浏览器地址栏敲 API 地址。GET 请求这样测最快。POST 就得开 Postman 或者用 curl。curl 更轻量：

curl -X POST https://example.com/api/login \ -H "Content-Type: application/json" \ -d '{ "username":"test","password":"123"}'

返回结果直接打在终端里，复制粘贴都方便。

API 接口暴露在公网上，任何人都能发请求。几个基本措施：HTTPS 必须上，敏感接口加频率限制，用户输入永远不要信任。

SQL 注入、XSS、CSRF 这些老问题，在 API 场景下依然存在。ORM 能挡住大部分 SQL 注入，但如果你手写拼接 SQL，那就自求多福。CORS 配置别偷懒写 *，尤其是带 cookie 的请求，浏览器根本不会放行。

还有一点：别把内部接口暴露到公网。我见过有人把管理后台的 API 直接放在公网域名下，只是前端没做入口。稍微会抓包的人都能直接调。

网页 API 接口是前端和后端之间的契约。契约清晰，两边都省事；契约混乱，调试两行泪。选什么风格、怎么版本控制、状态码怎么用，这些决定没有绝对的对错，但得在项目早期就想清楚。等到几十个接口上线了再重构，成本翻十倍不止。

相关推荐