如何理解RESTful API并用Flask实现简单的GET和POST接口

RESTful API是一种面向资源的接口设计风格，它借助HTTP协议本身的特性来定义接口的交互规则，核心思想是将所有操作的对象都抽象为资源，通过不同的HTTP请求方法对应资源的增删改查操作，相比传统的接口设计方式，它的结构更清晰，通用性更强，也更容易被不同端的开发者理解和使用。

RESTful API的核心设计原则

要理解RESTful API，首先需要掌握几个核心的设计要点：

• 资源抽象：所有需要操作的数据都抽象为资源，每个资源对应一个唯一的URI，比如用户资源的URI可以设计为/users，单个用户资源为/users/{id}。
• HTTP方法映射操作：不同的HTTP请求方法对应不同的资源操作，GET用于获取资源，POST用于创建新资源，PUT用于更新资源，DELETE用于删除资源。
• 状态码规范：使用标准的HTTP状态码返回请求结果，比如200表示请求成功，201表示资源创建成功，400表示请求参数错误，404表示资源不存在。
• 无状态性：每次请求都包含完整的信息，服务端不需要保存客户端的会话状态，这样更容易实现服务端的水平扩展。

Flask框架基础准备

Flask是Python生态中非常轻量的Web框架，适合快速开发接口。实现接口前需要先安装Flask依赖：

pip install flask

安装完成后，我们可以创建一个基础的Flask应用实例，后续所有的接口都基于这个实例来定义。

实现GET接口

GET接口通常用于获取资源数据，下面我们实现一个获取用户列表的GET接口，接口路径为/users，请求成功时返回预设的用户数据。

from flask import Flask, jsonify

# 创建Flask应用实例
app = Flask(__name__)

# 模拟用户数据存储
user_list = [
    {"id": 1, "name": "张三", "age": 25},
    {"id": 2, "name": "李四", "age": 28}
]

# 定义GET接口，路径为/users，仅支持GET请求
@app.route("/users", methods=["GET"])
def get_users():
    # 返回用户列表，使用jsonify自动转换为JSON格式，默认状态码为200
    return jsonify({
        "code": 200,
        "msg": "获取用户列表成功",
        "data": user_list
    })

if __name__ == "__main__":
    # 启动应用，默认监听127.0.0.1:5000
    app.run(debug=True)

启动应用后，使用浏览器或者接口测试工具访问http://127.0.0.1:5000/users，就能得到返回的用户列表数据。如果需要获取单个用户，可以添加带路径参数的接口，比如下面的示例：

@app.route("/users/<int:user_id>", methods=["GET"])
def get_single_user(user_id):
    # 遍历用户列表查找对应id的用户
    target_user = None
    for user in user_list:
        if user["id"] == user_id:
            target_user = user
            break
    # 如果找到用户返回对应数据
    if target_user:
        return jsonify({
            "code": 200,
            "msg": "获取用户成功",
            "data": target_user
        })
    # 未找到用户返回404状态码和错误提示
    return jsonify({
        "code": 404,
        "msg": "用户不存在"
    }), 404

实现POST接口

POST接口通常用于创建新的资源，下面我们实现一个创建新用户的POST接口，同样路径为/users，客户端传递用户的姓名和年龄，服务端生成新的用户id并添加到用户列表中。

from flask import request

@app.route("/users", methods=["POST"])
def create_user():
    # 获取请求的JSON数据
    request_data = request.get_json()
    # 校验必填参数是否存在
    if not request_data or "name" not in request_data or "age" not in request_data:
        return jsonify({
            "code": 400,
            "msg": "缺少必填参数name或age"
        }), 400
    # 生成新的用户id，这里简单取当前最大id加1
    new_id = max([user["id"] for user in user_list]) + 1 if user_list else 1
    # 构造新用户数据
    new_user = {
        "id": new_id,
        "name": request_data["name"],
        "age": request_data["age"]
    }
    # 添加新用户到列表
    user_list.append(new_user)
    # 返回创建成功的结果，状态码设为201表示资源创建成功
    return jsonify({
        "code": 201,
        "msg": "用户创建成功",
        "data": new_user
    }), 201

使用接口测试工具发送POST请求到http://127.0.0.1:5000/users，请求体设置为{"name": "王五", "age": 30}，就能看到返回创建成功的用户数据，再次访问GET接口也能看到新用户已经添加到列表中。

接口设计的注意事项

在实际开发RESTful API时，还需要注意几个细节：

• URI尽量使用名词复数形式，避免使用动词，比如使用/users而不是/getUsers，操作类型通过HTTP方法区分。
• 参数传递尽量使用请求体传递复杂数据，GET请求的参数可以放在查询字符串中，比如/users?age=25表示获取年龄为25的用户。
• 返回的数据结构尽量统一，比如都包含状态码、提示信息、数据字段，方便客户端统一处理响应。
• 做好参数校验和异常处理，避免无效请求导致服务端报错，返回合适的错误状态码和提示信息。

RESTful_APIFlaskGET接口POST接口修改时间：2026-06-12 06:24:26