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 |