API 接口规范——RESTful API、GraphQL、OpenAPI/Swagger

RESTful API设计风格

定义

RESTful API是一种设计风格,不是协议也不是标准,而是一种“约定俗成”的接口设计方式,强调资源导向和无状态通信

简单来说:把接口看做是对“资源”的操作

核心原则

原则说明
资源导向(Resources)把数据抽象成“资源”,如/users表示用户资源
使用HTTP方法表示操作GET、POST、PUT、EDLETE
无状态(Stateless)每次请求都独立,不依赖上一次的状态
统一接口(Uniform Interface)所有客户端与服务器通过统一的方式交互
版本控制(Versioning)接口路径中加版本号,如/api/v1/users

示例

用户管理接口

请求方法接口地址含义
GET/api/v1/users获取所有用户
GET/api/v1/users/1获取 ID 为 1 的用户
POST/api/v1/users创建一个新用户
PUT/api/v1/users/1更新 ID 为 1 的用户信息
DELETE/api/v1/users/1删除 ID 为 1 的用户

特点

  • 易于理解和维护

  • 支持缓存、跨平台调用

  • 广泛用于前后端分离架构、微服务系统

GraphQL

定义

GraphQL时Facebook提出的一种查询语言+运行时框架,它允许客户端按需获取数据,而不是像REST那样“服务器决定返回什么"

类似:REST是菜单固定的参订;GraphQL是自助餐,自己选择要吃什么

示例

获取用户信息(对比REST和GraphQL)

REST风格

GET /api/users/1
→ 返回全部字段(比如 name, age, address, phone...)

GraphQL 风格

query {
  user(id: "1") {
    name
    age
  }
}

只需要name和age字段

核心思想

概念说明
Schema(模式)定义API中有哪些类型和字段,类似数据库结构定义
Query(查询)用于读取数据
Mutation(变更)用于写入数据(新增、更新、删除)
R二solver(解析器)负责处理每个字段的数据来源(数据库、第三方接口等)

特点

  • 灵活:客户端自由选择需要的数据字段

  • 减少请求次数:一次请求获取多个资源

  • 强类型:Schema定义清晰,便于文档生成和自动校验

OpenAPI/Swagger

定义

OpenAPQ是一种用于描述RESTful API的标准格式,Swagger是实现这个标准的工具集之一。

OpenAPI就像是API的说明书,Swagger是这本说明说的”编辑器+展示器“

示例

OpenAPI规范文档片段(YAML格式)

openapi: 3.0.0
info:
  title: 用户管理系统 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

主要功能

  • 自动生成API文档(Swagger UI)

  • 提供在线测试接口的功能

  • 支持多种格式输出(JSON、YAML)

  • 可集成到CI/CD流程中进行自动化构建

工具推荐

  • Swagger UI:可视化展示API接口翁当

  • Swageer Editor:编写OpenAPI文档

  • Swagger Codegen:根据文档自动生成客户端或服务端代码

  • Reodc:另一种文档展示方式

使用场景

  • 团队协作开发,前后端对接

  • 第三方开发者接入API

  • 自动化测试和文档同步更新

总结对比

规范是否支持按需获取数据是否适合复杂查询是否自带文档功能是否主流
RESTful API❌(需手动写)✅✅✅ 广泛使用
GraphQL❌(需配合 GraphiQL)✅✅ 正在流行
OpenAPI / Swagger✅ 自动生成文档✅✅✅ 必备工具

场景推荐方案
初创项目、小型系统RESTful API + Swagger
微服务架构、前后端分离RESTful API + OpenAPI
数据结构复杂、频繁修改字段GraphQL
多个服务间聚合数据GraphQL 或 REST + BFF(后端为前端)
团队协作、文档驱动开发OpenAPI + Swagger UI
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值