Python 教程 / 用 Flask 创建 JSON API 并验证输入
Flask 可以把 HTTP 请求映射到 Python 函数,构成返回 JSON 的小型 API。添加记录之前,应检查对象形状、必填字段、类型和值,并用不同状态码表示创建成功与输入失败。
确定本机练习范围并安装 Flask
这个 API 只用于同一台电脑上的开发练习。支出保存在进程内的列表中,程序结束就消失,两个独立进程也不会共享同一个列表。JSON 数据表示并不等于持久存储。
先选择项目虚拟环境,再安装第三方包:
python -m pip install flask
使用 Python 3.12 以上的项目环境,把程序命名为 app.py,不要叫 flask.py,以免遮蔽安装的库。Flask 官方入门文档说明应用与路由的基本关系。公开服务还需要存储、认证、权限、部署和并发设计。
保存完整 API 程序
在独立练习目录中,将下面全部内容以 UTF-8 保存为 app.py:
from flask import Flask, jsonify, request
app = Flask(__name__)
app.config["MAX_CONTENT_LENGTH"] = 4096
expenses = []
@app.errorhandler(413)
def too_large(error):
return jsonify(error="request body too large"), 413
@app.get("/api/expenses")
def list_expenses():
return jsonify(expenses)
@app.post("/api/expenses")
def add_expense():
data = request.get_json(silent=True)
if not isinstance(data, dict):
return jsonify(error="expected JSON object"), 400
name, amount = data.get("name"), data.get("amount")
if not isinstance(name, str) or not name.strip() or type(amount) is not int or amount < 0:
return jsonify(error="invalid name or amount"), 400
row = {"id": len(expenses) + 1, "name": name.strip(), "amount": amount}
expenses.append(row)
return jsonify(row), 201
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000, debug=False)
在该目录执行 python app.py 可启动本机开发服务器,监听 127.0.0.1:5000,debug 已关闭。如果实际解释器命令是 python3,则相应替换;端口被占用时,修改代码中的 port 与客户端地址,勿停止无关程序。
GET /api/expenses 返回列表和状态 200。POST 到同一路径时,应发送包含非空名称和非负整数金额的 JSON 对象,例如 {"name":"lunch","amount":8000};成功创建返回 201,并去除名称两侧空白。
名称空白、金额负数、布尔值、字符串金额或错误形状的输入会返回 400,不追加记录。silent=True 使无法读取的 JSON 返回 None,再由对象检查返回规定错误。这里只明确处理这些路径,不应理解为所有服务器错误都必定返回同一种 JSON。
MAX_CONTENT_LENGTH=4096 限制请求正文的字节数,超过时通过专用处理器返回 JSON 与 413。它不限制列表最终记录数、所有内存资源或所有操作时长,当前代码也没有规定正金额的业务上限。
用测试客户端验证路由
把下面完整文件保存为同目录中的 test_client.py:
from app import app, expenses
expenses.clear()
with app.test_client() as client:
created = client.post("/api/expenses", json={"name":"lunch", "amount":8000})
assert created.status_code == 201
for payload in [{"name":"x","amount":True}, {"name":"x","amount":-1}, {"name":" ","amount":1}, [1,2]]:
response = client.post("/api/expenses", json=payload)
assert response.status_code == 400 and response.is_json
assert client.post("/api/expenses", data="{", content_type="application/json").status_code == 400
too_large = client.post("/api/expenses", data="x"*5000, content_type="application/json")
assert too_large.status_code == 413 and too_large.is_json
rows = client.get("/api/expenses")
assert rows.status_code == 200 and len(rows.get_json()) == 1
print(created.status_code, rows.get_json()[0]["amount"])
print("validation and 413 checks passed")
从该目录运行:
python test_client.py
预期输出两行:201 8000 和 validation and 413 checks passed。测试先创建一条有效记录,再尝试错误输入,最后要求列表只保留那一条。不要加 -O 优化参数执行,因为它会移除普通 assert 检查。
这个测试不需要单独启动服务器。app.test_client 在 Python 进程中经过 Flask 的请求处理流程,不测试真实 HTTP 连接、代理或部署环境。main 入口保护让 import app 不会启动监听端口。
expenses.clear() 只清空当前测试进程中的列表,不会清空另一个终端已启动服务器的独立内存。测试成功不能证明那个独立服务器里有同样的记录,也不能证明网络配置已经正确。
理解类型检查、错误边界和数据寿命
JSON true 转换成 Python bool,而 isinstance(True, int) 为真;所以本例用 type(amount) is int 精确排除布尔金额。零仍有效,8.0 和字符串 "8" 都不满足这个类型契约。
错误 JSON、数组、负数与空白名称返回 400,过大正文返回 413。未定义路径的 404、错误方法的 405 仍可能使用 Flask 默认 HTML;代理在到达应用前拒绝请求时,也不受这个处理器保证。详见Flask 错误处理文档和正文大小限制配置。
ID 取自 len(expenses) + 1,适合此控制演示,不能代替并发服务中的标识与同步机制。重复 POST 会创建重复内容,不包含基于内容去重的规则。增加删除、多个工作进程或持久化之前,应重新设计标识与一致性。
如果曾启动本机开发服务器,完成后用 Ctrl+C 停止。重新运行将得到新的空列表。需要持久保存时可结合SQLite 存储与事务设计;开发服务器与交互调试器不用于公开部署。




