SuperAPI AI 工具集

rest-api

编程与开发

查看项目

更新于 10-16 10:11

技能介绍

用途

Rest API 技能用于按照项目约定编写 REST API 端点,目标是保持一致性、安全性和渐进增强。当需要创建 API 端点、实现后端接口,或处理 HTTP 方法与状态码、同时支持 JSON 与表单编码请求、实现版本策略、构建支持 HTML 表单回退的端点时适用。

主要能力

HTTP 方法

提供标准方法的 Express 示例:GET 读取、POST 创建、PUT 整体替换资源、PATCH 局部更新、DELETE 删除。

表单回退(API_METHOD)

由于 HTML 表单只支持 GET 和 POST,为实现渐进增强,提供中间件读取隐藏字段 API_METHOD,在 POST 请求中将其转换为 PUT/PATCH/DELETE,使无 JavaScript 时也能执行这些方法。资料给出中间件实现和一个删除用户的表单示例。

内容类型

通过同时启用 express.json() 与 express.urlencoded({ extended: true }),使 req.body 对 application/json 与 application/x-www-form-urlencoded 都可用。

响应内容协商

提供 respond 辅助函数,根据 Accept 头判断客户端接受 HTML 还是 JSON,若接受 HTML 且有模板则渲染模板,否则返回 JSON。

状态码

列出成功码(200、201、204)、客户端错误码(400、401、403、404、409、422、429)和服务器错误码(500、502、503),并说明各自适用时机与示例。

标准错误响应格式

提供 sendError 函数,输出包含 error.code、error.message 与可选 details 的结构,并给出 400/401/404/422 的用法示例。

版本管理

优先使用基于请求头的版本管理:从 Accept-Version 或 API-Version 头读取版本,默认最新稳定版,并提供 versionRouter 中间件按版本选择处理器;URL 版本(/api/v2 等)仅保留给需要整体重设计的破坏性变更。

流式大响应

提供 streamJsonArray 逐条写出 JSON 数组以降低内存占用、改善 TTFB,并给出配合数据库游标使用的示例;同时提供 NDJSON(application/x-ndjson,每行一个 JSON 对象)的替代方案。

限流

提供基于内存的简单限流中间件(windowMs、max、keyGenerator),设置 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 响应头,超限返回 429;资料提示生产或多实例环境应使用 Redis,并演示了对 /api 与 /api/auth 应用不同限额。

令牌鉴权

提供 Bearer Token 中间件:检查 Authorization 头是否以 Bearer 开头,取出令牌并校验,失败返回 401 的 MISSING_TOKEN 或 INVALID_TOKEN,成功后把载荷挂到 req.user。

第三方 API 代理

演示在服务端持有 API Key 代理第三方地理编码接口,对返回结果做格式转换,密钥不下发给客户端,并可在前端不变的情况下更换供应商;上游失败时返回 502。

输入验证

建议在边界处验证、不信任客户端输入,提供 validateBody、validateQuery、validateParams 中间件用法示例,并说明校验 schema 存放在 /schemas/ 目录。资料未给出 schema 的具体编写细节,仅指向验证技能。

健康检查端点

提供四类端点:/health 基础健康检查(返回状态、时间戳、运行时长);/ready 就绪检查(检查数据库、Redis 等依赖,任一不健康返回 503);/live 存活检查(如堆内存使用超过 95% 时返回 503);/startup 启动检查(迁移与缓存预热完成后标记启动完成)。并给出健康检查响应的 OpenAPI schema 示例。

HTTP 缓存

说明 Cache-Control 的各种取值及适用场景(public/private、no-cache、no-store、immutable、stale-while-revalidate),并演示静态资源、可缓存动态资源、用户级缓存与敏感数据禁缓存的写法;同时提供基于响应体 MD5 生成 ETag 的函数与条件请求中间件,命中时返回 304。

使用方式

资料中所有示例均以 Express/Node.js 代码片段给出,通过引入相应中间件与辅助函数、在路由上挂载后即可使用。安装命令、包管理器配置与项目初始化步骤暂未提供。

适用场景

创建 API 端点、处理 HTTP 方法与状态码、同时支持 JSON 与表单请求、实现版本策略、构建支持 HTML 表单回退的端点。

限制

资料未说明所支持的语言或框架范围(示例均为 Express)、未提供收费或许可信息、未提供安装方式、未给出 schema 的具体编写规范,也未说明限流中间件在生产多实例下的具体替代实现细节。