文本协议
文本协议具有可读性好、易于调试的优点。
📋 RESTful API 设计
RESTful API 设计原则：
RESTful API 示例：
java
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
@GetMapping
public ResponseEntity<PageResult<User>> getUsers(...) {
// 获取用户列表
}
@GetMapping("/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
// 获取单个用户
}
@PostMapping
public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) {
// 创建用户
}
@PutMapping("/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody UpdateUserRequest request) {
// 更新用户
}
@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
// 删除用户
}
}📋 GraphQL
GraphQL vs REST：
GraphQL 示例：
graphql
type Query {
user(id: ID!): User
users(page: Int, size: Int): [User]
}
type User {
id: ID!
name: String!
email: String!
posts: [Post!]
}GraphQL 查询示例：
graphql
# 查询用户及其文章
query {
user(id: "1") {
id
name
email
posts {
id
title
content
}
}
}📋 RESTful API 最佳实践
1. URL 设计规范
设计原则：
- 使用名词：使用名词表示资源，不使用动词
- 使用复数：资源使用复数形式（如
/users） - 层级清晰：使用层级结构组织资源（如
/users/{id}/orders） - 版本控制：在URL中包含版本信息（如
/api/v1/users）
示例：
markdown
✅ 好的设计：
GET /api/v1/users # 获取用户列表
GET /api/v1/users/{id} # 获取单个用户
POST /api/v1/users # 创建用户
PUT /api/v1/users/{id} # 更新用户
DELETE /api/v1/users/{id} # 删除用户
❌ 不好的设计：
GET /api/getUser # 使用动词
POST /api/user/create # 使用动词
GET /api/users?id=1 # 应该使用路径参数2. HTTP 方法使用
方法语义：
| 方法 | 语义 | 幂等性 | 安全性 |
|---|---|---|---|
| GET | 获取资源 | 是 | 是 |
| POST | 创建资源 | 否 | 否 |
| PUT | 完整更新资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| DELETE | 删除资源 | 是 | 否 |
3. 状态码使用
常用状态码：
- 200 OK：请求成功
- 201 Created：资源创建成功
- 204 No Content：删除成功，无返回内容
- 400 Bad Request：请求参数错误
- 401 Unauthorized：未认证
- 403 Forbidden：未授权
- 404 Not Found：资源不存在
- 409 Conflict：资源冲突
- 500 Internal Server Error：服务器错误
📋 GraphQL 最佳实践
1. GraphQL 设计原则
核心原则：
- 类型安全：定义清晰的类型系统
- 查询灵活性：客户端可以按需查询字段
- 单端点：使用单一端点处理所有查询
- 强类型系统：使用 Schema 定义数据类型
2. GraphQL vs REST 选型
选型建议：
| 场景 | 推荐方案 | 理由 |
|---|---|---|
| 简单CRUD | REST | 简单直接，开发效率高 |
| 复杂查询 | GraphQL | 灵活查询，减少请求次数 |
| 移动端应用 | GraphQL | 按需查询，节省流量 |
| 第三方集成 | REST | 标准化程度高，易于集成 |
3. GraphQL 实现示例
Spring Boot + GraphQL 实现：
java
@Configuration
public class GraphQLConfig {
@Bean
public GraphQLSchema graphQLSchema() {
return GraphQLSchema.newSchema()
.query(queryType())
.build();
}
private GraphQLObjectType queryType() {
return GraphQLObjectType.newObject()
.name("Query")
.field(GraphQLFieldDefinition.newFieldDefinition()
.name("user")
.type(userType())
.argument(GraphQLArgument.newArgument()
.name("id")
.type(Scalars.GraphQLString))
.dataFetcher(env -> {
String id = env.getArgument("id");
return userService.findById(id);
}))
.build();
}
}📋 其他文本协议
1. JSON-RPC
特点：
- 远程过程调用：类似RPC的调用方式
- JSON格式：使用JSON格式传输数据
- 无状态：每个请求独立
示例：
json
{
"jsonrpc": "2.0",
"method": "getUser",
"params": {"id": 1},
"id": 1
}2. XML-RPC
特点：
- XML格式：使用XML格式传输数据
- 简单协议：协议简单，易于实现
- 跨语言：支持多种编程语言
📖 学习资源
视频教程
书籍推荐
- 《RESTful Web APIs》 - Leonard Richardson, Mike Amundsen
- 《GraphQL学习指南》 - Eve Porcello, Alex Banks
- 《HTTP权威指南》 - David Gourley, Brian Totty
- 《API设计模式》 - JJ Geewax
网站资源
工具推荐
- API测试工具：Postman、Insomnia、Apifox
- API文档工具：Swagger、Redoc、Stoplight
- GraphQL工具：GraphQL Playground、GraphiQL、Apollo Studio
✅ 文本协议检查清单
- [ ] 理解RESTful API设计原则
- [ ] 掌握HTTP方法的使用
- [ ] 掌握状态码的使用
- [ ] 理解GraphQL的设计思想
- [ ] 能够选择合适的协议方案
- [ ] 能够设计规范的API接口
- [ ] 能够编写完整的API文档