Flask后端工程化实战：从单文件到高可用部署的踩坑指南

1. 项目概述：一个"简单"Flask服务是如何把我折磨到凌晨的

事情是这样的，前阵子接了个内部小工具的需求：后端用 Flask 暴露一组接口，前端页面调用，其中还涉及对接第三方大模型 API 做文本处理。需求听起来真不大——管理后台嘛，增删改查加一个 AI 接口，我当时预估三天搞定。

结果这个"三天搞定"的项目，硬生生拖了一周半。每天都有新坑，而且很多坑不是 Flask 本身的问题，是工程化落地时才暴露出来的。比如前端联调时接口被人跨域拦截了、本地跑得好好的接口部署到服务器上就超时、调用大模型 API 时报各种 400/529 错误，甚至有一回因为模板渲染没注意安全直接被提醒存在注入风险。

这篇文章就是那段时间的踩坑记录。整理成"日记"的形式，按我实际开发的时间线来写。如果你正准备用 Flask 做后端接口服务，或者已经写了个能跑的 hello world 但不知道怎么扩展成真正的工程，这篇应该能帮你少走不少弯路。里面涉及的内容包括工程结构设计、跨域与接口规范、第三方 API 调用时的异常处理、Docker 部署和几个安全细节，我会尽量把当时踩坑的现象、排查思路和最终解法都讲清楚。

2. 工程结构：从单文件 app.py 到分模块的痛苦蜕变

2.1 一开始的"能跑就行"埋下了多大的雷

我最早写 Flask 和大多数人一样，一个 app.py 从头写到尾。路由、数据库连接、Redis 缓存、日志配置、第三方 API 调用全塞在一个文件里。demo 阶段没问题，跑起来看效果特别爽。但当接口数量从 3 个涨到 15 个，当开始要接用户认证、账单管理、统计分析这些模块时，单文件模式的噩梦就开始了。

最明显的痛点是改一个功能要拉着滚动条在几千行里找对应的函数。然后是你根本不敢加新功能，因为函数之间的隐式依赖太多了，一个全局变量的改动可能影响三个路由。再后来协同开发的同事拉代码下来，看半天也不知道该从哪看起。这就是单文件 Flask 项目的极限——它适合教学，不适合当工程。

我建议如果你准备做一个接口数量超过 10 个、或者要持续维护的后端服务，一开始就按模块分目录。别想着"等写多了再重构"，我重构那次花了整整一个周末，改到后面我连自己原来写的代码都想不起来当初为什么这么写。

2.2 用 Blueprint 拆分业务模块的正确姿势

Flask 的 Blueprint（蓝图）机制就是干这个的。它的核心作用是把路由注册、模板、静态文件按模块拆开，最后在应用工厂里统一注册。我当时是这么分的：

text复制flask_app/
├── app/
│   ├── __init__.py          # 应用工厂 create_app()
│   ├── config.py            # 配置文件
│   ├── extensions.py        # db、redis 等扩展实例
│   ├── api/
│   │   ├── __init__.py
│   │   ├── auth.py          # 登录认证相关接口
│   │   ├── bills.py         # 账单相关接口
│   │   ├── stats.py         # 统计分析接口
│   │   └── ai_chat.py       # 大模型调用接口
│   ├── services/            # 业务逻辑层
│   ├── models/              # 数据模型
│   ├── utils/               # 工具函数
│   └── errors.py            # 全局异常处理
├── tests/
├── run.py                   # 启动入口
├── requirements.txt
└── Dockerfile

api/ 目录下每个模块都创建一个 Blueprint，比如 auth.py 大致是：

python复制from flask import Blueprint, request, jsonify

auth_bp = Blueprint("auth", __name__, url_prefix="/api/v1/auth")


@auth_bp.route("/login", methods=["POST"])
def login():
    data = request.get_json()
    # 处理逻辑...
    return jsonify({"code": 0, "message": "ok", "data": {...}})

然后在 app/__init__.py 的应用工厂里注册：

python复制def create_app():
    app = Flask(__name__)
    app.config.from_object("app.config.Config")

    # 注册扩展
    from app.extensions import db
    db.init_app(app)

    # 注册蓝图
    from app.api.auth import auth_bp
    from app.api.bills import bills_bp
    app.register_blueprint(auth_bp)
    app.register_blueprint(bills_bp)

    return app

用 url_prefix 给所有接口统一挂上 /api/v1/ 前缀，这个是 RESTful 设计里常见做法。好处很多：一方面接口版本升级时可以平滑过度，另一方面前端代理拦截路径也方便——比如 Nginx 转发时只要匹配 /api/ 前缀就行。

这里有个细节值得注意：我把 db、redis 这些扩展实例单独放在 extensions.py 里，而不是直接在 __init__.py 里初始化。原因是为了避免循环引用。因为 models 里的数据模型要引用 db，如果 db 在 app 包里定义，models 再 import app 就容易出现依赖循环。单独抽一层 extensions 模块，models 和 app 都只依赖它，依赖方向就清晰了。

2.3 配置管理：不要把所有环境塞进一份代码

另一个工程化必须解决的问题是配置。开发环境、测试环境、生产环境的数据库地址、API Key、调试开关都不一样。我之前图省事直接写在代码里，后来要部署到服务器时只能手动改代码，改了还容易漏。

推荐的做法是建一个 config.py，按环境分 Class：

python复制class BaseConfig:
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL", "sqlite:///app.db")
    REDIS_URL = os.environ.get("REDIS_URL", "redis://localhost:6379/0")


class DevConfig(BaseConfig):
    DEBUG = True
    # 开发环境可以打印 SQL 日志之类


class ProdConfig(BaseConfig):
    DEBUG = False
    # 生产环境从环境变量读，而不是写死在代码里

启动时通过环境变量指定用哪个配置：FLASK_ENV=production python run.py。这样同一份代码在不同环境跑，行为不同但逻辑一致，不会出现"本地好好的，线上挂了"这种因为配置不同导致的问题。

3. 前后端联调：CORS 和接口规范这些事

3.1 前端报跨域错误的底层原因与解法

后端接口写好了，前端联调第一关就是跨域。现象很清楚：浏览器控制台报：

text复制Access to XMLHttpRequest at 'http://localhost:5000/api/v1/auth/login'
from origin 'http://localhost:8080' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

原理上是浏览器默认的同源策略：前端页面跑在 localhost:8080，你的后端在 localhost:5000，端口不同就属于跨域。Flask 自己返回的响应头里没有 Access-Control-Allow-Origin，浏览器就把响应拦截了。注意，这时候接口本身是正常返回的，是浏览器不让你读。

最简单省事的方案是装 Flask-CORS：

bash复制pip install flask-cors

然后：

python复制from flask_cors import CORS

def create_app():
    app = Flask(__name__)
    CORS(app)
    return app

默认配置是允许所有来源访问。开发阶段无所谓，但生产环境最好限制来源：

python复制CORS(app, resources={r"/api/*": {"origins": ["https://yourdomain.com"]}})

这里有个坑我踩过：一开始用 @app.after_request 手动给响应加 Access-Control-Allow-Origin 头，GET 请求没问题，但 PUT、DELETE 请求还是会失败。原因是浏览器对于跨域的复杂请求（比如带自定义 Header、用 PUT/DELETE 方法）会先发一个 OPTIONS 预检请求，你的后端如果没有正确处理 OPTIONS，正式请求就不会发出来。Flask-CORS 这个库内部已经处理了预检逻辑，所以不要自己造轮子，老老实实用库。

3.2 统一响应格式：前后端扯皮的第一来源

接口数量一多，前后端最容易出现的矛盾就是响应格式不统一。有的接口成功返回 {"status": "success", "data": [...]}，有的接口返回 {"code": 200, "result": {...}}，还有的接口直接把数据扔在顶层。前端同学要接每个接口都看一遍文档，还总在群里问"这个字段是啥意思"。

绕不开的问题是"接口规范"。我个人实践下来比较好用的统一格式是：

json复制{
  "code": 0,
  "message": "ok",
  "data": {}
}

• code 是业务码，0 表示成功，非 0 表示各类业务错误（比如 1001 参数错误、1002 未登录、1003 无权限）
• message 是人可读的描述信息
• data 是实际业务数据

后端实现一个统一返回的辅助函数：

python复制from flask import jsonify


def ok(data=None, message="ok"):
    return jsonify({"code": 0, "message": message, "data": data})


def fail(code, message, data=None):
    return jsonify({"code": code, "message": message, "data": data})

所有接口都走这两个函数，前端只要处理 code 就行，非 0 弹错误提示，0 则正常取 data。HTTP 状态码也按语义来：成功返回 200，参数错误返回 400，未认证返回 401，资源不存在返回 404。业务逻辑层面的失败靠 code 表达，传输层面的失败靠 HTTP 状态码表达，两层不要混。

3.3 RESTful 设计里最容易忽略的三个细节

RESTful 接口规范听起来是个老生常谈，但真写起来容易犯几个错：

第一个是用动词当 URL。比如 /api/deleteBill、/api/getUserInfo 这种。RESTful 的建议和思考其实很简单：URL 只表示资源，方法表示动作。删除账单应该是 DELETE /api/v1/bills/123，获取用户信息是 GET /api/v1/users/456。这样接口列表一眼看过去就知道系统里有哪些资源，而不是看一堆动词。

第二个是不管什么操作一律用 GET。有些人图省事，查询用 GET，新增也用 GET 拼参数，删除也用 GET。副作用很大的操作，比如删除数据、修改账单，放在 GET 里很容易被浏览器预加载、被爬虫触发，而且 URL 会暴露太多信息。正确的原则是：查询用 GET，新增用 POST，修改用 PUT/PATCH，删除用 DELETE。

第三个是返回的数据结构不嵌套。比如账单列表里有用户名称，有人会直接把用户对象塞到账单数据里，形成很深的嵌套。前端取数据的成本会增加不少，而且数据冗余。合理的做法是只返回 user_id，前端需要用户名时单独调用户详情接口，或者后端在响应里提供最小必要的关联字段。这个根据业务场景取舍，但不要无脑嵌套。

4. 调用大模型 API 的实战错误清单与处理策略

4.1 529 Overloaded：服务端过载时的重试策略

这个项目的核心功能是调用大模型 API 做文本处理。当时用的是 DeepSeek 的接口，一切都挺顺利，直到某天下午接口突然大面积报错：

text复制api error: 529 overloaded. This is a server-side issue, usually temporary.

看到 529 这个状态码第一反应是懵的。查了一下才知道，这是大模型服务端负载过高时专门用的一个状态码，表示服务器当前处理不过来，但注意它区别于 5xx 的严重故障——它通常是一时的，过一会儿就好。这和 HTTP 503 类似，但也有区别：529 是特定服务商自定义的，语义更明确地指向负载过重。

遇到 529 的处理方式很简单：重试。但重试不是无脑重试，要讲究策略。

我一开始写的是请求失败就立即重试，结果服务端还在过载，照样 529，两个小时后服务端恢复了我才停止报错，但那会儿已经浪费了大量请求和等待时间。后来改成指数退避的策略：

python复制import time
import random


def call_model_with_retry(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIError as e:
            if e.status_code != 529:
                raise
            wait_time = 2 ** attempt + random.uniform(0, 1)
            time.sleep(wait_time)
    raise APIError("max retries exceeded")

指数退避的数学逻辑在于：重试等待时间按 1 秒、2 秒、4 秒、8 秒、16 秒递增，加上一个随机抖动，避免多个客户端同时重试造成"惊群效应"——所有客户端在同一个时间点一起打过来，服务端缓过来了也被打瘫了。加随机值的意义就是让每个客户端的重试时间错开。

后来我又加了一个预处理：后端主动探测大模型服务的可用性，有一段时间不可用时直接返回提示信息给前端，不发起真实请求，避免堆积。这个操作的意义在于，前端页面刷不出来不能干等，要给用户一个明确的"服务繁忙，请稍后重试"的反馈。

4.2 Connection lost mid-response：流式输出的断连问题

第二个高频报错是这个：

text复制api error: connection lost mid-response. The response above may be incomplete.

这个报错出现在流式请求中。现代大模型 API 大多支持流式输出（流式传输的过程其实和普通的 HTTP 响应不同——服务器会先把响应头发回来，然后一块一块地推送正文，客户端逐块接收）。我的后端需要把模型返回的内容以流式方式转发给前端，前端才能实现"打字机"效果。

如果前端主动断开连接（比如用户点了停止生成、或者刷新了页面），后端的流式请求就不会断，还在继续从模型服务端拉数据。这些数据如果继续处理就浪费了，因为前端已经不会接收了。更麻烦的是，流式请求中途网络抖动，会导致连接在中间位置断开，返回 incomplete 的数据给到下游。

我当时排查了很久才意识到问题的根源在于：模型服务端的连接超时设置太短，当生成内容比较长、耗时超过连接保持时间时，服务端就主动断开连接了。

解决方案有几个层面：一是给请求设置合理的超时参数，比如连接超时 10 秒、读取超时 60 秒，别用默认值；二是后端要有"部分内容"的处理逻辑——如果流式中断了，要判断已收到的内容能不能用，不能直接丢了让用户重新生成一遍；三是后端转发流式数据到前端时，要监听前端的断开事件，及时取消上游请求。

Python 里用 requests 库做流式请求时，核心代码大概是：

python复制import requests
from flask import Response, stream_with_context


@app.route("/api/v1/ai/chat", methods=["POST"])
def chat():
    def generate():
        stream = client.chat.completions.create(
            model="deepseek-chat",
            messages=messages,
            stream=True,
            timeout=60,
        )
        for chunk in stream:
            delta = chunk.choices[0].delta.content
            if delta:
                yield delta
            # 如果前端断开，这里会发生 GeneratorExit

    return Response(stream_with_context(generate()), content_type="text/event-stream")

这里有个细节：一定要用 stream_with_context 包装生成器，否则在流式响应过程中 Flask 的请求上下文会提前关闭，你如果需要在生成器里访问 request 或 session 会报错。这个坑我之前遇到时特别不好排查——报错信息是在第一次迭代时才触发，不是启动时。

4.3 400 参数错误：thinking_budget 和 max_tokens 的那些坑

调用第三方大模型 API 时另一大类高频报错是 400 参数错误。我遇到过的有：

text复制api error: 400 the thinking_budget parameter must be a positive integer and...

这种报错看着头大，但其实原因很简单：某一个参数不符合服务端的约束。thinking_budget 这个参数在模型能力里用于控制推理预算，它必须是一个正整数。我当时传了一个浮点数（比如 1.5），后端校验直接拒绝了。

还有一次是：

text复制api error: 400 this model's maximum context length is 1048576 tokens. However, your messages resulted in 1100000 tokens.

这里本质是 token 超限。token 是模型处理文本的基本单位，一般来说 1 个英文单词约等于 1.3 个 token，1 个中文汉字约等于 0.6-0.8 个 token。不同模型有不同的上下文窗口上限。1048576 tokens 这个窗口其实非常大了，但我当时是把历史对话记录全量传给模型，前几十轮对话的完整文本加起来就超了。

这类问题的解法是上下文管理策略。简单来说有三种：

1. 滑动窗口：只保留最近 N 轮对话。
2. 按 token 数裁剪：用 tiktoken 或各 SDK 自带的 tokenizer 统计消息总 token 数，超出上限时从最旧的对话开始丢弃。
3. 摘要压缩：把早期对话生成一个摘要文本，替换掉原始内容。

我最终的方案是先用工具统计 token 数，如果超限就保留最近 10 轮完整对话，更早的压缩成一两句话的摘要。这样效果和成本平衡得比较好。

另外，接大模型 API 时参数命名、类型、取值范围这些最好先去查官方文档确认，因为不同模型的同名参数含义可能完全不同。比如 max_tokens 在有的模型里表示"最多生成多少个 token"，在另一个模型里表示"总上下文长度"，理解错了传参就是 400。我后来整理了一份参数对照表放在项目 README 里，方便随时查。

4.4 Socket Connection Closed：连接池与 Keep-Alive 的排查实录

这个报错信息很长：

text复制cannot connect to api: the socket connection was closed unexpectedly. For more information, check the browser console and/or the network tab.

虽然不是发生在我的服务端调模型 API 时，但排查思路完全通用。当时是前端跑在本地，连不上部署在测试服务器的后端接口，报 socket connection was closed unexpectedly。

排查时我先在浏览器开发者工具里看网络面板，发现请求是 pending 状态很久后突然变为 failed。然后用 curl 在服务器本地直接访问后端接口，发现能通。再用 curl 从客户端机器访问，发现也不通。基本能判断问题出在中间链路——服务器防火墙或者反向代理配置。

后来发现是 Nginx 配置里的 proxy_read_timeout 设置的太短，请求处理时间超过这个阈值就被 Nginx 掐断了。把 timeout 调到 300 秒后问题解决。

这类 socket 层的问题排查，记住一个口诀：先本地、再跨机器、最后看中间链路。分清是后端进程没起来、防火墙挡了、还是代理超时。90% 的"请求突然断了"问题都出在代理层的 time out 配置上，而不是业务代码。

5. Docker 部署与开发环境的实操复盘

5.1 Windows 上 Docker API 连接失败的经典报错

部署阶段第一个坑就出在 Docker 本身上。Windows 上启动 Docker Desktop 后，命令行执行 docker ps 报错：

text复制failed to connect to the docker api at npipe:////./pipe/dockerDesktopLinuxEngine...

这个报错的意思是 Docker 客户端通过 Windows 命名管道去连接 Docker 引擎，但连接不上。具体到我的情况，是 Docker Desktop 启动到一半失败了（原因是系统进行了大版本更新后虚拟化组件版本不一致），但界面还没弹出来错误提示。

排查时先确认 Docker Desktop 是否真正启动完成。右下角图标变绿之前，任何 docker 命令都会报这个错。如果图标一直停在加载状态，先把 Docker Desktop 完全退出再重新启动。如果还不行，检查 Windows 设置里的 Hyper-V 和虚拟机平台功能是否开启——这两个是 Docker Desktop 在 Windows 上运行 Linux 容器的基础依赖。

更稳妥的做法是启动后先跑 docker info 验证引擎可用，再跑业务命令。我后来写了个小脚本，在 CI 流程第一步骤检查 Docker 引擎健康状态，避免流程跑到一半才发现引擎没起来。

5.2 Flask 自带的服务器不能用于生产

这是老生常谈但真的很多人踩：Flask 自带的 app.run() 服务器只适合开发调试，不适合生产部署。原因很简单：它单进程单线程，同一时间只能处理一个请求（后续版本虽然支持多线程，但性能远不如专业 WSGI 服务器），也没有优雅地处理大量并发连接的能力。

生产环境我用的是 Gunicorn。Dockerfile 里的启动命令可以是这样：

dockerfile复制FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "run:app"]

这里 -w 4 表示启动 4 个 worker 进程。worker 数量不是越多越好，一般经验值是 CPU 核数 * 2 + 1。因为 Python 有 GIL 锁，多线程在同进程内并不能充分利用多核，所以用多进程来提升并发能力。但 worker 太多会导致内存占用飙升——每个 worker 都会加载完整的应用代码。

部署后还要在 Nginx 层做反向代理，静态文件（比如用户上传的图片、前端构建产物）由 Nginx 直接返回，只有 /api/ 路径的请求转发给 Gunicorn。这能显著减轻 Flask 应用的压力，因为 Python 处理静态文件 I/O 的效率远不如 Nginx。

5.3 本地验证通过但部署失败：环境差异排查法

部署中另一个典型问题是本地跑得好好的，部署到服务器就报错。我当时的报错是 Python 版本引起的——本地用的 3.11，服务器镜像里的基础环境是 3.9，一个用了 str | None 类型语法的地方在 3.9 下直接语法错误。

这类环境差异问题，最好的解法是"用和线上一致的环境做本地开发"。Dockerfile 里基础镜像版本固定住，本地也用它。另一个容易踩的是依赖库版本范围，requirements.txt 里最好锁版本，不要写 >=，否则今天装的是 1.0，明天变 2.0，接口行为变了根本不知道。我用 pip freeze 把版本全部固定下来后，这类问题几乎绝迹。

还有 environment variable 的坑——本地开发时 .env 文件里的数据库地址是 localhost，部署后容器里的 localhost 指向容器本身，而不是宿主机。用 Docker Compose 编排时，服务之间要用服务名访问：

yaml复制services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/appdb
  db:
    image: postgres:15

在 web 容器里，数据库地址要填 db，不是 localhost。这个"localhost 幻觉"是新手部署容器时最容易犯的错。

6. 安全避坑：SSTI 与接口鉴权

6.1 模板渲染不小心就变成执行代码

Flask 的模板引擎 Jinja2 支持在模板里写 Python 风格的表达式，这本来是方便动态渲染的，但如果你把用户输入直接拼进模板字符串再用 render_template_string 渲染，就存在模板注入（SSTI）的风险——攻击者可以通过构造特定的模板表达式来执行任意代码。

网上有个经典的实验室叫 Flask SSTI Lab，专门用来练习这类漏洞。我当时是在做日志管理功能时，想在前端展示一段用户提交的文本，代码写成了：

python复制from flask import render_template_string

template = "<div>{{ user_input }}</div>"
return render_template_string(template, user_input=user_input)

表面看没问题，user_input 作为变量被渲染进模板。但如果参数是 {{ config }}，它会被解析成 Flask 的配置对象并展示出来，里面可能有密钥信息。如果再深入构造表达式，甚至可以调用底层 Python 对象链执行系统命令。

防御方案其实很简单：永远不要把用户输入拼进模板字符串里。用普通的字符串拼接或者在前端渲染数据。如果确实需要在 Jinja2 里动态渲染，要确保用户输入作为数据传入，而不是作为模板代码。也就是说 render_template_string(template, user_input=user_input) 里 user_input 的值只会被当作数据，不会当模板代码执行。真正危险的是把用户输入直接变成 template 的一部分：

python复制# 危险写法
template = f"<div>{user_input}</div>"  # user_input 被当成模板源码
return render_template_string(template)

这两种写法的区别,在于 render_template_string 会把 template 参数当作模板源码编译执行,而通过关键字传入的变量只是数据。我在代码评审时专门把这条写进了团队规范：所有用户输入在渲染前必须经过 html 转义，且不能作为模板源码的一部分。

6.2 接口鉴权：token 过期与刷新机制

后端接口如果没有鉴权，等于把大门敞开。基础的鉴权方案是 JWT（JSON Web Token）。Flask 里比较成熟的库是 flask-jwt-extended：

python复制from flask_jwt_extended import create_access_token, jwt_required


@app.route("/api/v1/auth/login", methods=["POST"])
def login():
    # 校验用户名密码
    token = create_access_token(identity=user.id)
    return ok(data={"token": token})


@app.route("/api/v1/bills", methods=["GET"])
@jwt_required()
def list_bills():
    user_id = get_jwt_identity()
    # 查询该用户的账单

JWT 本身的机制是服务器签发一个带签名的 token 给客户端，客户端后续请求在 Header 里带上 Authorization: Bearer <token>，服务器验签即可。优点是服务端不需要存储 session，天然适合前后端分离和分布式部署。

坑点在于 token 过期时间设置。太短前端频繁要求重新登录，太长又有安全风险。常见做法是用短期 access_token（比如 30 分钟）加长期 refresh_token（比如 7 天），access_token 过期后用 refresh_token 换新的。flask-jwt-extended 提供了 create_refresh_token 和 @jwt_required(refresh=True) 来支持这套流程，算是比较省心的方案。

另一种需要注意的安全细节是登录失败时的错误信息不要暴露太多线索。不管是"用户不存在"还是"密码错误"，统一返回"用户名或密码错误"。否则攻击者可以通过枚举响应信息来探测系统里有哪些用户名存在，方便后续做定向攻击。这个细节很多入门教程都不提，但实际安全性影响挺大。

7. 常见问题排查速查表与个人体会

7.1 高频错误与对应排查方向

这张表是我踩完这些坑之后整理的速查版。每次遇到类似的报错，先对着表看一遍，能省掉很多重复排查时间。

7.2 关于"踩坑日记"这个系列的几句话

写这篇踩坑日记的过程，其实也是我重新梳理 Flask 后端开发方法论的过程。回顾这一周半的经历，有几个体会比较深：

第一个体会是"能跑"和"能上线"之间差着十万八千里。单文件 app.py 跑起来容易，但一旦涉及多人协作、多环境部署、安全审计，工程化的基本功才是决定项目能不能长期维护的关键。Blueprint 拆模块、配置分离、统一响应格式这些不是炫技，是实打实的生产需求。

第二个体会是调用第三方 API 时，错误处理要比业务逻辑花更多心思。大模型 API 和普通 REST API 不太一样，它更不稳定——过载、断流、参数限制、token 超限都是常态。你不能假设一个请求一定成功，必须把失败当默认路径来设计。重试要有退避策略，流向要有超时控制，上下文要有裁剪机制。

第三个体会是调试网络问题要有方法论。从客户端到服务端一层一层排查，而不是靠猜。前端请求被浏览器拦截了先看浏览器控制台；服务器响应异常先 curl 本地测；socket 断连先看代理层 timeout。很多时候看着是代码问题，实际是配置问题。

后面几篇日记我准备继续写测试覆盖、性能压测、日志链路追踪这些方向。Flask 这个框架入门门槛低，但做到"稳健"确实需要踩不少坑。希望这篇记录能给你的开发过程省下一些时间。