深入理解 RESTful API：请求与响应详解及实战代码示例

最新推荐文章于 2026-07-26 14:27:30 发布
原创 最新推荐文章于 2026-07-26 14:27:30 发布 · 499 阅读 · 4 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
GEO检测

1. 什么是 RESTful API？

REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，用于设计网络应用程序的接口。RESTful API 是基于 REST 原则设计的 API，它使用标准的 HTTP 方法（GET、POST、PUT、DELETE 等）对资源进行操作，并通过 HTTP 状态码和媒体类型（如 JSON、XML）进行通信。

RESTful API 的核心特征包括：

  • 无状态（Stateless）：每个请求都包含处理该请求所需的全部信息，服务器不保存客户端状态。
  • 统一接口（Uniform Interface）：使用标准的 HTTP 方法和资源标识符（URI）。
  • 资源导向（Resource-Oriented）：将数据和功能都视为资源，通过 URI 进行标识。
  • 可缓存（Cacheable）：响应应明确标识是否可缓存，以提高性能。
  • 分层系统（Layered System）：客户端无需知道是否直接连接到最终服务器。

2. RESTful API 请求详解

2.1 HTTP 方法（动词）

RESTful API 使用 HTTP 方法来定义对资源的操作意图：

  • GET：获取资源（安全且幂等）。
  • POST：创建新资源。
  • PUT：更新整个资源（幂等）。
  • PATCH：部分更新资源。
  • DELETE：删除资源（幂等）。
  • HEAD：获取资源的元信息。
  • OPTIONS：获取资源支持的通信选项。

2.2 请求头（Headers）

请求头携带了关于请求的元数据，常见的有：

  • Content-Type：请求体的媒体类型，如 application/json、application/xml。
  • Accept：客户端期望的响应媒体类型。
  • Authorization：身份验证凭证，如 Bearer Token。
  • User-Agent：客户端软件信息。

2.3 请求体（Body）

对于 POST、PUT、PATCH 请求，通常需要携带请求体来传递数据。JSON 是目前最常用的格式。

// 创建用户的请求体示例
{
  "username": "john_doe",
  "email": "john@example.com",
  "age": 30,
  "active": true
}

2.4 查询参数（Query Parameters）与路径参数（Path Parameters）

路径参数用于标识特定资源，通常作为 URI 的一部分：

GET /api/users/123
GET /api/posts/456/comments

查询参数用于过滤、排序、分页等：

GET /api/users?role=admin&active=true
GET /api/products?category=electronics&sort=price&page=2&limit=20

3. RESTful API 响应详解

3.1 HTTP 状态码（Status Codes）

状态码表示请求的处理结果：

  • 2xx 成功
    • 200 OK：请求成功。
    • 201 Created：资源创建成功。
    • 204 No Content：请求成功，但无返回内容。
  • 3xx 重定向
    • 301 Moved Permanently：资源永久移动。
    • 302 Found：资源临时移动。
  • 4xx 客户端错误
    • 400 Bad Request：请求语法错误。
    • 401 Unauthorized：未认证。
    • 403 Forbidden：无权限。
    • 404 Not Found：资源不存在。
    • 422 Unprocessable Entity：请求格式正确但语义错误。
  • 5xx 服务器错误
    • 500 Internal Server Error：服务器内部错误。
    • 502 Bad Gateway：网关错误。
    • 503 Service Unavailable：服务不可用。

3.2 响应头（Response Headers）

响应头携带了关于响应的元数据，常见的有：

  • Content-Type：响应体的媒体类型。
  • Content-Length：响应体的大小。
  • Cache-Control：缓存控制指令。
  • Location（常用于 201 Created）：新创建资源的 URI。

3.3 响应体（Response Body）

响应体包含了请求的结果数据。成功的响应通常遵循一致的格式。

// 成功响应示例（包含数据）
{
  "status": "success",
  "data": {
    "id": 123,
    "username": "john_doe",
    "email": "john@example.com"
  },
  "message": "User retrieved successfully"
}
// 错误响应示例
{
"status": "error",
"code": 400,
"message": "Invalid email format",
"details": {
"field": "email",
"reason": "Must be a valid email address"
}
}

4. 实战代码示例

4.1 使用 Python Flask 创建 RESTful API

from flask import Flask, request, jsonify
from flask_sqlalchemy import SQLAlchemy
app = Flask(name)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///users.db'
db = SQLAlchemy(app)
数据模型
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True, nullable=False)
def to_dict(self):
    return {
        'id': self.id,
        'username': self.username,
        'email': self.email
    }
创建数据库表
with app.app_context():
db.create_all()
获取所有用户 (GET /api/users)
@app.route('/api/users', methods=['GET'])
def get_users():
users = User.query.all()
return jsonify({
'status': 'success',
'data': [user.to_dict() for user in users],
'count': len(users)
}), 200
获取单个用户 (GET /api/users/<id>)
@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
user = User.query.get(user_id)
if not user:
return jsonify({
'status': 'error',
'code': 404,
'message': f'User with id {user_id} not found'
}), 404
return jsonify({
    'status': 'success',
    'data': user.to_dict()
}), 200
创建用户 (POST /api/users)
@app.route('/api/users', methods=['POST'])
def create_user():
data = request.get_json()
# 验证必要字段
if not data or 'username' not in data or 'email' not in data:
    return jsonify({
        'status': 'error',
        'code': 400,
        'message': 'Username and email are required'
    }), 400
检查用户是否已存在
if User.query.filter_by(username=data['username']).first():
return jsonify({
'status': 'error',
'code': 409,
'message': f'Username {data["username"]} already exists'
}), 409
创建新用户
new_user = User(username=data['username'], email=data['email'])
db.session.add(new_user)
db.session.commit()
return jsonify({
'status': 'success',
'data': new_user.to_dict(),
'message': 'User created successfully'
}), 201
更新用户 (PUT /api/users/<id>)
@app.route('/api/users/<int:user_id>', methods=['PUT'])
def update_user(user_id):
user = User.query.get(user_id)
if not user:
return jsonify({
'status': 'error',
'code': 404,
'message': f'User with id {user_id} not found'
}), 404
data = request.get_json()
if 'username' in data:
user.username = data['username']
if 'email' in data:
user.email = data['email']
db.session.commit()
return jsonify({
'status': 'success',
'data': user.to_dict(),
'message': 'User updated successfully'
}), 200
删除用户 (DELETE /api/users/<id>)
@app.route('/api/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
user = User.query.get(user_id)
if not user:
return jsonify({
'status': 'error',
'code': 404,
'message': f'User with id {user_id} not found'
}), 404
db.session.delete(user)
db.session.commit()
return jsonify({
'status': 'success',
'message': f'User with id {user_id} deleted successfully'
}), 204
if name == 'main':
app.run(debug=True)

4.2 使用 JavaScript (Fetch API) 调用 RESTful API

// 基础配置
const API_BASE_URL = 'http://localhost:5000/api';
// 获取所有用户
async function fetchUsers() {
try {
const response = await fetch(${API_BASE_URL}/users);
if (!response.ok) {
throw new Error(HTTP error! status: ${response.status});
}
const result = await response.json();
console.log('Users:', result.data);
return result.data;
} catch (error) {
console.error('Error fetching users:', error);
throw error;
}
}
// 获取单个用户
async function fetchUser(userId) {
try {
const response = await fetch(${API_BASE_URL}/users/${userId});
if (!response.ok) {
if (response.status === 404) {
console.log(User ${userId} not found);
return null;
}
throw new Error(HTTP error! status: ${response.status});
}
const result = await response.json();
console.log('User:', result.data);
return result.data;
} catch (error) {
console.error(Error fetching user ${userId}:, error);
throw error;
}
}
// 创建用户
async function createUser(userData) {
try {
const response = await fetch(${API_BASE_URL}/users, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userData)
});
    const result = await response.json();
if (!response.ok) {
    throw new Error(result.message || 'Failed to create user');
}
console.log('User created:', result.data);
return result.data;
} catch (error) {
console.error('Error creating user:', error);
throw error;
}
}
// 更新用户
async function updateUser(userId, updateData) {
try {
const response = await fetch(${API_BASE_URL}/users/${userId}, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(updateData)
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.message || 'Failed to update user');
}
console.log('User updated:', result.data);
return result.data;
} catch (error) {
console.error(Error updating user ${userId}:, error);
throw error;
}
}
// 删除用户
async function deleteUser(userId) {
try {
const response = await fetch(${API_BASE_URL}/users/${userId}, {
method: 'DELETE'
});
if (!response.ok && response.status !== 204) {
const result = await response.json();
throw new Error(result.message || 'Failed to delete user');
}
console.log(User ${userId} deleted successfully);
return true;
} catch (error) {
console.error(Error deleting user ${userId}:, error);
throw error;
}
}
// 使用示例
async function exampleUsage() {
// 1. 获取所有用户
const users = await fetchUsers();
// 2. 创建新用户
const newUser = await createUser({
username: 'alice_smith',
email: 'alice@example.com'
});
// 3. 获取刚创建的用户
const user = await fetchUser(newUser.id);
// 4. 更新用户
await updateUser(newUser.id, {
email: 'alice.new@example.com'
});
// 5. 删除用户
await deleteUser(newUser.id);
}
// 运行示例
exampleUsage().catch(console.error);

4.3 使用 Java Spring Boot 创建 RESTful API

// User.java - 实体类
package com.example.restapi.model;
import jakarta.persistence.*;
@Entity
@Table(name = "users")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(unique = true, nullable = false)
private String username;
@Column(unique = true, nullable = false)
private String email;
// 构造方法、Getter 和 Setter
public User() {}
public User(String username, String email) {
this.username = username;
this.email = email;
}
// Getters and Setters
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
}
// ApiResponse.java - 统一响应格式
package com.example.restapi.dto;
public class ApiResponse<T> {
private String status;
private T data;
private String message;
public ApiResponse(String status, T data, String message) {
this.status = status;
this.data = data;
this.message = message;
}
// 成功响应工厂方法
public static &lt;T&gt; ApiResponse&lt;T&gt; success(T data) {
return new ApiResponse&lt;&gt;("success", data, null);
}
public static &lt;T&gt; ApiResponse&lt;T&gt; success(T data, String message) {
return new ApiResponse&lt;&gt;("success", data, message);
}
// 错误响应工厂方法
public static ApiResponse&lt;?&gt; error(String message) {
return new ApiResponse&lt;&gt;("error", null, message);
}
// Getters and Setters
public String getStatus() { return status; }
public void setStatus(String status) { this.status = status; }
public T getData() { return data; }
public void setData(T data) { this.data = data; }
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
}
// UserController.java - 控制器
package com.example.restapi.controller;
import com.example.restapi.model.User;
import com.example.restapi.dto.ApiResponse;
import com.example.restapi.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
@RequestMapping("/api/users")
public class UserController {
@Autowired
private UserService userService;
// GET /api/users - 获取所有用户
@GetMapping
public ResponseEntity&lt;ApiResponse&lt;List&lt;User&gt;&gt;&gt; getAllUsers() {
List&lt;User&gt; users = userService.getAllUsers();
return ResponseEntity.ok(ApiResponse.success(users, "Users retrieved successfully"));
}
// GET /api/users/{id} - 获取单个用户
@GetMapping("/{id}")
public ResponseEntity&lt;
标签
#restful #后端
lideiguo
关注
手把手掌握OkHttp与Retrofit：企业级RESTful API实战详解
全栈
05-16 1067
本文深入解析OkHttp与Retrofit在企业级Android开发中的实践，从基础配置到高级功能（如动态Base URL、拦截器、缓存优化、协程支持）提供完整代码示例。通过结合HTTP/2、请求重试、文件上传等场景，帮助开发者构建高效、稳定的网络请求架构，提升应用性能与可维护性。
基于C#的RESTful API开发实战案例详解
weixin_35750483的博客
10-31 1232
首先定义实体模型：set;set;set;set;接着编写控制器：[HttpGet][HttpGet]关键点解析：路由约束：确保 ID 至少为 1，防止无效访问。：仅返回激活状态的产品，体现软删除理念。NotFound()：资源不存在时返回 404，避免暴露内部状态。参数类型请求方式默认来源是否需显式标注简单类型（int, string）GET/POSTURI否复杂类型（class）
深入实战：使用C++开发高性能RESTful API
编程技术探索者，分享C/C++、C#、Java、数据库等开发经验，聚焦实战技巧与AI兴趣，助力编程爱好者成长。
04-19 2480
是基于REST（Representational State Transfer）架构风格构建的应用程序接口。REST由Roy Fielding在其博士论文中提出，强调通过无状态的通信协议（通常是HTTP）来管理和交换资源。RESTful API利用HTTP协议的动词（如GET、POST、PUT、DELETE）来操作资源，具有简单、可扩展和易于维护的特点。本文通过详细的讲解和实战案例，深入探讨了如何在C++中开发高性能的RESTful API。
深入理解 RESTful 风格 API 设计与 Go 语言实现
m0_57836225的博客
01-04 813
RESTful 风格并非严格意义上的规范，而是一种软件架构风格或设计理念，类似于面向对象编程中的基本原则。它为 API 设计提供了一系列指导原则，使得 API 的设计更加符合网络应用的特点，便于理解和使用。RESTful 风格 API 设计为构建高效、可维护和易于理解的网络应用接口提供了一套有效的原则和方法。通过合理的资源命名、使用 HTTP 方法进行操作、准确的状态码返回、合适的响应格式以及有效的版本控制和错误处理机制，我们能够打造出高质量的 API，提升系统的整体性能和用户体验。
前端网络请求全解析：请求头、响应头与状态码详解
Yue
02-22 1728
前端开发者必须深入理解HTTP协议中的请求头、响应头和状态码，这些知识不仅是调试和优化网络请求的基础，也是构建安全、高效Web应用的关键。通过合理配置请求头、正确理解状态码、优化响应头设置，开发者可以显著提升应用的性能和用户体验。随着Web技术的不断发展，这些基础知识将继续发挥重要作用，帮助开发者构建更好的Web应用。
深入理解Vert.X与Kotlin打造RESTful API
weixin_35753431的博客
04-09 823
本篇博客深入探讨了如何使用Vert.X框架结合Kotlin语言开发RESTful API。通过创建ProductVerticle类，展示了如何定义路由、处理HTTP请求以及返回JSON数据。同时，本文还介绍了如何通过添加排序参数来扩展API功能，以及如何通过HTTP GET方法查询特定对象。
JSON API标准详解：构建高效RESTful API的终极指南
gitblog_00301的博客
12-27 803
在现代Web开发中，RESTful API设计已成为构建高效后端服务的黄金标准。而JSON API作为RESTful API设计中的重要规范，为开发者提供了一套完整的JSON数据格式标准，帮助构建更加统一和可维护的API接口。本文将深入解析JSON API标准的核心概念和最佳实践，帮助您快速掌握这一强大的API设计工具。 ## 🚀 什么是JSON API标准？ JSON API是一种用于构建
深入理解 RESTful API 设计与实践
qq_17405059的博客
03-14 1133
首先，需要明确 API 中的资源。用户（User）文章（Article）评论（Comment）RESTful API 是一种基于 HTTP 的架构风格，提供清晰的资源 URL和HTTP 方法进行交互。设计 RESTful API 时应遵循 REST 原则，包括资源、统一接口、无状态、可缓存、分层架构。API 需要保证安全性，使用身份验证、权限控制和 HTTPS。RESTful API 广泛应用于 Web 开发、移动开发、微服务架构。
【RESTful】深入理解RESTful API：设计高效Web服务的关键
人生苦短，睡觉要紧，睡醒再说
11-01 2224
RESTful API是一种通过HTTP进行通信的应用程序接口，其设计遵循REST（表现层状态转化）架构风格。REST的核心思想是将资源视为网络上的实体，并通过统一的接口进行操作。每个资源通常通过URI（统一资源标识符）进行标识和访问。在RESTful API中，标准的HTTP方法（如GET、POST、PUT和DELETE）被用来操作这些资源。资源可以是任何可以被命名的内容，例如用户、产品、订单等。RESTful API的设计遵循一系列约定，确保客户端与服务器之间能够高效、清晰地进行交互。
RESTful API设计样例代码解析
weixin_36178216的博客
09-13 3419
本文还有配套的精品资源，点击获取 简介：RESTful是一种基于HTTP协议的网络应用程序设计风格，它通过使用URI定位资源和HTTP方法操作资源，以提高开发效率和API的可维护性。本文将解析RESTful API设计的关键元素，包括URI设计、HTTP方法、状态码、CRUD操作、数据格式、版本控制、认证与授权、错误处理、分页与过滤以及HATEOAS。通过样例代码的展示，开...
106、Rust HTTP与RESTful API：深入理解与实战技巧
silenceallat的博客
04-23 2399
本文介绍了Rust语言中HTTP协议与RESTful API的处理方式，包括HTTP请求和响应的处理，以及RESTful API的设计原则。通过实例和技巧，读者可以更好地理解如何在Rust中实现HTTP请求、处理响应，并设计出符合REST原则的API。文章还讨论了RESTful API的实际应用场景，如用户认证、博客系统和电子商务等。掌握HTTP协议和RESTful API设计对于软件开发者来说是非常重要的技能，它们是现代网络服务的基石。
深入理解HTTP协议与RESTful API设计
weixin_35433448的博客
04-08 946
本章深入探讨了HTTP协议及其与Java的交互，包括作为客户端和服务端的不同用途。详细介绍了HTTP方法、状态码、以及如何在Java中使用专门的HTTP客户端库来发送请求。还探讨了RESTful API设计的基本原则和实践，包括如何设计REST URI和处理RESTful请求。本章强调了理解HTTP和REST工作原理的重要性，无论是在服务器端还是前端开发中。
Flask-RESTX资源类：深入理解RESTful API的核心组件
gitblog_00008的博客
04-22 667
Flask-RESTX是一个功能全面的框架，专为使用Flask快速、轻松地开发带文档的API而设计。资源类（Resource Class）作为Flask-RESTX的核心组件，为构建RESTful API提供了强大的基础。本文将深入探讨Flask-RESTX资源类的概念、功能和使用方法，帮助开发者更好地理解和应用这一核心组件。 ## 什么是Flask-RESTX资源类？ 在Flask-REST
《零基础学 PHP：从入门到实战》· PHP接口开发与前后端分离实战-理解HTTP协议与RESTful API设计
zwh821的博客
12-13 1033
本章深入讲解HTTP协议与RESTful API设计规范，重点包括：HTTP协议基础（请求/响应模型、无状态特性）；关键HTTP方法（GET/POST/PUT/DELETE）的语义与使用场景；常见状态码分类（2xx/4xx/5xx）及其应用；请求头/响应头的作用；RESTful架构的核心原则（资源中心化、统一接口等）和URI设计规范。通过图书管理系统API案例，将理论知识与实践结合，为后续API开发奠定基础。掌握这些"对话规则"对构建规范、安全的Web服务至关重要。
【RESTful】深入理解 RESTful Api 架构
spirit_peri的博客
01-06 320
非原创，搬运地址： http://mengkang.net/623.html 一些常见的误解 不要以为 RESTful Api 就是设计得像便于 SEO 的伪静态，例如一个 Api 的 URL 类似于 http://xxx.com/blog/1 ，我们可以通过浏览器访问该 URL 而读取文章，但是这并不代表着它就是 RESTful Api 。 也不要认为URL 里有 queryString 就不是 RESTful Api ，例如 http://xxx.com/users/?page=10&page
构建RESTful API与数据序列化的最佳实践
weixin_35756624的博客
05-07 881
本文深入探讨了使用ASP.NET Core构建RESTful API的高级技术。涵盖从创建产品API、数据验证到实现CRUD操作，以及如何正确处理请求和响应格式和错误处理。展示了如何通过Entity Framework Core进行数据库交互和数据序列化，并强调了使用ASP.NET Core内置工具确保API的可靠性。
深入理解RESTful API设计与实现
weixin_42576467的博客
05-10 399
本文深入探讨了在ASP.NET Core环境下设计RESTful API的实践过程，包括创建、存储和检索资源的具体步骤。通过详细的代码示例和解释，我们学习了如何使用DTOs、映射器和仓库模式来处理HTTP请求，并确保代码的清晰和安全。特别强调了POST方法的安全性和幂等性问题，以及如何处理子资源的创建。文章还介绍了如何创建资源集合的API，以及如何通过一个请求同时处理父资源及其子资源。
使用Laravel构建RESTful API
weixin_34511754的博客
05-15 449
本章节介绍了如何在Laravel框架中构建一个遵循JSON API规范的RESTful API。通过编写测试用例和中间件，确保API能够正确处理符合规范的请求和响应头。内容涵盖了创建中间件、注册中间件到路由和API中间件组、以及在测试中模拟请求和响应来满足API规范。
深入理解API：从概念到实战
小白的博客
05-24 1489
本文系统介绍了API（应用程序编程接口）的概念与应用。API是一组预定义的规则和协议，允许不同软件组件交互，类比餐厅点餐的流程。文章解析了API的工作原理，基于客户端-服务器模型，通过示例展示天气API调用。详细分类了Web API、系统级API、库/框架API和硬件API等主要类型，并提供了RESTful API设计原则。最后通过JavaScript、Python等代码演示API调用方式，强调API安全与认证机制，指出掌握API对提升开发效率、构建可扩展系统的重要性。
藏在正则表达式里的陷阱
最新发布
Hdp08v0Tt的博客
07-26 274
# 一、正则表达式的基础：从简单匹配开始正则表达式（Regular Expression，简称 regex）是一种描述字符串模式的语法。它让文本处理变得优雅，但也暗藏陷阱：从简单的转义错误、方法选择不当，到复杂的贪婪匹配导致性能灾难、Unicode编码误解，再到严重的安全漏洞。它看起来合理，但如果你用它匹配一个非常长的无效字符串（如"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"），正则引擎会因嵌套量词和可选组而进入指数级回溯。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值