SuperAPI AI 工具集

api design skill

编程与开发

查看项目

更新于 10-15 21:40

技能介绍

用途:帮助设计直观、一致且不易误用的 API,核心原则是面向消费者而非实现。

主要能力:REST 基础规范(资源用名词复数、路径参数表身份、查询参数表过滤;GET/POST/PUT/PATCH/DELETE 的语义与幂等性;常用状态码适用场景);契约优先流程(先写 OpenAPI/Swagger,与消费者评审后再生成服务端桩、实现逻辑并校验响应);版本策略(URL 路径、请求头、查询参数三种方式对比,推荐 URL 路径,并给出 Active/Deprecated/Sunset 生命周期);分页(偏移量与游标两种模式及各自优劣);统一错误结构(机器可读 code、人类可读 message、details、request_id,禁止暴露堆栈);请求响应一致性(命名风格统一、ISO 8601 时间、ID 用字符串、信封结构、部分响应、批量操作);缓存(Cache-Control、ETag、Last-Modified、Vary 及决策矩阵、应用层缓存与失效策略);限流(固定窗口、滑动窗口、令牌桶、漏桶,响应头与分层配额、客户端重试处理、网关配置示例)。

企业集成模式:整理 Microsoft Graph Planner、Azure DevOps、Qualtrics、Microsoft Fabric 等平台的限制与做法,如订阅过期、ETag 更新、JSON Patch、异步 202 轮询、令牌获取,以及用队列解耦、持久化映射的多平台同步架构。

使用方式:作为设计参考与评审清单使用,按需查阅对应章节;资料未提供安装命令或具体调用方式。

限制:内容为设计指导,未说明收费、平台支持范围或实际效果;部分平台限制可能随官方变化,需以官方文档为准。