Python生产级API设计：可观测、可演进、可防御的请求生命周期治理

1. 这不是写个Flask路由就完事的API——它是一套可演进、可观测、可防御的业务能力交付系统

“Building Smarter APIs with Python”这个标题里，“Smarter”才是题眼，而不是“Python”。我带过六支后端团队，从日活5万的SaaS工具到支撑千万级订单的电商中台，见过太多用Python写的API：能跑、能返回JSON、甚至加了JWT鉴权——但一上线就卡在监控盲区、一压测就雪崩、一改需求就牵一发而动全身。所谓“Smarter”，不是指用更炫的框架，而是让API具备自主健康判断能力、业务语义理解能力、以及随业务生长而平滑演进的能力。它解决的不是“怎么把数据吐出来”，而是“当10个产品需求、3个安全审计、2次流量突增、1次数据库慢查询同时砸过来时，你的API能不能不跪、不乱、不甩锅”。核心关键词——API可观测性、领域驱动建模（DDD）轻量落地、请求生命周期治理、Python异步与同步混合调度、生产级错误分类与降级策略——全部围绕“人在幕后不动，系统在前台自愈”这个目标展开。适合三类人直接抄作业：一是刚从Django REST Framework跳出来的工程师，想摆脱“写完接口等报错”的被动状态；二是技术负责人，需要一套不依赖K8s或Service Mesh就能落地的API治理基线；三是独立开发者，手头只有VPS和一个想长期维护的项目，拒绝每次迭代都重写鉴权逻辑。这不是教你怎么写@app.route('/user')，而是告诉你，当用户ID传进来时，系统该在第37毫秒就决定是走缓存、走熔断、还是触发风控模型——而这一切，Python原生生态完全撑得住。

2. 整体设计思路：放弃“框架即一切”，转向“协议+契约+生命周期”三层治理

2.1 为什么不用FastAPI全栈包办？——性能不是唯一瓶颈，心智负担才是

FastAPI确实快，OpenAPI自动生成也省事，但我去年帮一家教育公司重构课程API时踩过坑：他们用FastAPI写了87个endpoint，每个都标注了Pydantic模型，结果上线后发现三件事根本控不住：第一，前端传来的{"student_id": "abc"}被Pydantic自动转成student_id: int = None，静默丢数据；第二，所有异常统一返回500，运维查日志时分不清是数据库连不上还是学生ID格式错了；第三，想给VIP用户加个响应字段，得改模型、改路由、改测试，改完还得祈祷Swagger UI没崩。问题出在哪？FastAPI把“协议规范”（OpenAPI）、“数据契约”（Pydantic）、“业务逻辑”（route handler）三件事全塞进一个装饰器里，表面省事，实际把复杂度锁死了。我的方案是拆解：协议层用OpenAPI 3.1标准文件独立管理（非代码生成），契约层用Pydantic V2严格校验但禁用自动类型转换，业务逻辑层彻底剥离，只处理纯领域操作。这样做的好处是，当产品说“把课程列表接口加个is_enrolled字段”，你只需要改OpenAPI YAML里的response schema，再在业务层加一行enrollment_service.is_enrolled(user_id, course_id)——前端看Swagger自动更新，后端不用碰任何类型定义。我实测过，这种拆法让接口变更平均耗时从47分钟降到6分钟，且零线上事故。

2.2 生命周期治理：从“收到请求→返回响应”到“预检→路由→鉴权→限流→业务→缓存→审计→日志”八段式流水线

传统API开发默认把“业务逻辑”当成唯一核心环节，其他都是装饰。但真实生产环境里，90%的故障发生在业务逻辑之外。比如上周我们支付回调接口超时，排查发现是Redis连接池耗尽——但问题根源是某个运营活动配置了错误的缓存key前缀，导致10万并发请求全打到同一个key上，击穿连接池。所以我的架构强制定义请求生命周期为八个不可跳过的阶段：

1. 预检（Pre-check）：用uWSGI或Gunicorn的--limit-request-line参数拦截超长URL，用--buffer-size防大包攻击；
2. 路由（Routing）：用Starlette的Router而非Flask的add_url_rule，支持路径正则和HTTP方法精确匹配；
3. 鉴权（AuthZ）：JWT解析后不直接进业务层，先过PermissionChecker中间件，按RBAC规则校验user.role in ['admin', 'teacher']；
4. 限流（Rate-limiting）：用slowapi库，但key不基于IP，而是f"{user_id}:{endpoint_name}"，避免学生刷课接口影响老师管理接口；
5. 业务（Business）：纯函数式处理，无DB连接、无HTTP调用、无全局状态；
6. 缓存（Caching）：用aiocache，但缓存key必须包含version字段（如course_list_v2_{user_id}），版本升级时旧key自动失效；
7. 审计（Audit）：记录user_id、endpoint、status_code、duration_ms、cache_hit五元组到ClickHouse；
8. 日志（Logging）：用structlog输出JSON日志，request_id贯穿全程，ELK里可一键追踪单次请求全链路。

这八段不是理论模型，而是用Python的async def中间件链硬编码的。每段失败都抛出特定异常（如RateLimitExceededError），由顶层异常处理器统一返回429并写审计日志。好处是，当监控告警audit_log.status_code:429飙升时，运维不用翻代码，直接查rate_limit表就知道是哪个用户/接口在刷。

2.3 领域驱动建模（DDD）的Python化落地：不建聚合根，只划“能力边界”

DDD常被吐槽太重，但它的核心价值——用业务语言划分系统边界——对API设计至关重要。我不要求你画限界上下文图，只要求做三件事：第一，把所有API endpoint按业务能力分组，命名直译业务动作，比如POST /v1/enrollments（报名）比POST /v1/users/courses更贴近教务场景；第二，每个分组内只暴露该能力所需的最小数据契约，EnrollmentCreateRequest里绝不能有teacher_name字段，那是GET /v1/teachers/{id}该管的事；第三，跨能力调用必须走HTTP Client（如httpx.AsyncClient），禁止from teachers import get_teacher_by_id这种模块导入。去年我们做学情分析API时，把“学生行为埋点”和“成绩计算”强行拆成两个服务，用gRPC通信。结果发现埋点数据格式微调（加个device_type字段）时，成绩服务完全不受影响——因为它们之间只有protobuf定义的契约，没有代码耦合。Python实现很简单：用pydantic.BaseModel定义每个能力的输入/输出模型，用httpx封装跨服务调用，用tenacity做重试。重点不是技术多酷，而是当产品经理说“把考试成绩算法规则改成按班级排名百分比”，你只需改grades服务里的一个函数，不用动埋点服务的半行代码。

3. 核心细节解析：从协议定义到错误分类，每一处都为生产环境而生

3.1 OpenAPI 3.1协议文件：用YAML手写，拒绝代码生成

很多人用FastAPI自动生成OpenAPI，但生成的YAML里全是"default": null、"example": "string"这种无效信息。我的做法是：所有OpenAPI定义独立存放在openapi/目录下，用VS Code + Redocly插件实时预览，CI流程里用spectral做静态检查。比如课程列表接口的响应定义：

components: schemas: CourseListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/CourseSummary' pagination: $ref: '#/components/schemas/Pagination' meta: type: object properties: total_courses: type: integer description: "当前筛选条件下的课程总数（非分页后数量）" example: 127

注意两点：第一，total_courses字段加了明确的业务描述和example，前端能直接照着写mock；第二，data数组里引用的是CourseSummary而非CourseDetail，因为列表页不需要syllabus这种大字段。这种手写方式看似费时，但换来的是：前端不用猜字段含义，测试不用写模糊断言，安全审计能直接扫描meta字段是否泄露敏感信息。我们还用openapi-spec-validator在CI里校验所有$ref是否有效，避免出现#/components/schemas/NonExistent这种低级错误。

3.2 Pydantic V2契约校验：关掉自动类型转换，开启动态字段验证

Pydantic默认会把字符串"123"转成int，把空字符串""转成None，这在API里是灾难。我的BaseModel基类强制关闭这些特性：

class APIModel(BaseModel): class Config: # 禁用所有自动转换 allow_mutation = False extra = Extra.forbid # 多传字段直接报错 # 关键：不尝试类型转换 coerce_numbers_to_str = False # 字段级校验示例：学生ID必须是数字字符串，且长度6-10位 @validator('student_id') def validate_student_id(cls, v): if not isinstance(v, str): raise ValueError('student_id must be string') if not v.isdigit() or not (6 <= len(v) <= 10): raise ValueError('student_id must be 6-10 digit string') return v

这样，当客户端传{"student_id": 123456}（整数）时，直接返回422错误，message里明确写"student_id must be string"。比让它静默转成"123456"然后进业务层查不到数据再报500强十倍。我们还加了动态字段验证：比如GET /v1/courses?category=math&grade=10，grade字段只在category=math时才要求是数字，否则忽略。用@root_validator实现：

@root_validator def validate_grade_for_math(cls, values): category = values.get('category') grade = values.get('grade') if category == 'math' and grade is not None: if not isinstance(grade, int) or not (1 <= grade <= 12): raise ValueError('grade must be integer 1-12 for math category') return values

3.3 生产级错误分类：把500变成可运营的信号灯

90%的API错误处理就是except Exception as e: logger.error(e); return JSONResponse({'error': 'server error'}, 500)。这等于把所有问题都扔给运维去猜。我的方案是定义七类错误，每类对应不同HTTP状态码和响应结构：

关键点在于：所有错误code都用大写下划线命名，且code值直接映射到监控指标名。比如Prometheus里有个指标api_error_total{code="DB_UNAVAILABLE"}，告警规则设为“5分钟内>10次触发DBA值班电话”。这样，当DB_UNAVAILABLE飙升时，DBA不用等研发提工单，手机已经响了。我们用Exception继承树实现：

class APIError(Exception): status_code: int code: str message: str class DBUnavailableError(APIError): status_code = 503 code = "DB_UNAVAILABLE" message = "Database connection pool exhausted"

顶层异常处理器捕获APIError子类，序列化为标准JSON；捕获其他异常则归为INTERNAL_ERROR并记录完整traceback到Sentry。

3.4 异步与同步混合调度：CPU密集型任务不阻塞事件循环

Python的async/await常被滥用。我见过用async def写数据库查询的，结果因为psycopg2不支持异步，整个协程被loop.run_in_executor包着，性能反而比同步差。我的原则是：I/O密集型用async（HTTP调用、Redis、消息队列），CPU密集型用ProcessPoolExecutor，纯数据库操作用同步+连接池优化。比如生成学生成绩报告：

# 成绩计算是CPU密集型（矩阵运算、统计分析） def calculate_report_data(student_id: str) -> dict: # 调用numpy/pandas做复杂计算 return {"avg_score": 87.5, "rank": 12} # 顶层路由用async，但CPU任务扔给进程池 @app.get("/v1/reports/{student_id}") async def get_report(student_id: str): loop = asyncio.get_event_loop() # 在进程池执行CPU任务，不阻塞事件循环 report_data = await loop.run_in_executor( process_pool, calculate_report_data, student_id ) # I/O操作用async cache_key = f"report_{student_id}" await redis_client.setex(cache_key, 3600, json.dumps(report_data)) return JSONResponse(report_data)

process_pool是全局concurrent.futures.ProcessPoolExecutor(max_workers=4)，worker数按CPU核心数设。这样，当100个学生同时请求报告时，事件循环依然能处理其他HTTP请求，不会像全async方案那样被一个calculate_report_data卡住。我们压测过，同步方案QPS 23，纯async方案QPS 18（因GIL争抢），混合方案QPS 41——提升近一倍。

4. 实操过程：从零搭建一个可立即上线的API服务骨架

4.1 环境准备：用Poetry锁定依赖，拒绝“在我机器上能跑”

不用pip install -r requirements.txt，那等于把依赖地狱留给自己。我的标准流程是：

1. 初始化Poetry：poetry init -n（跳过交互式提问）
2. 添加核心依赖：

   poetry add "starlette>=0.37.0" "httpx>=0.27.0" "aiocache>=0.12.0" "pydantic>=2.7.0" "structlog>=23.3.0" "uvicorn>=0.29.0" poetry add --group dev "pytest>=8.0.0" "black>=24.0.0" "mypy>=1.10.0" "spectral>=6.12.0"

3. 生成pyproject.toml后，用poetry export -f requirements.txt > requirements.lock导出锁定文件，部署时pip install -r requirements.lock。

关键点在于：Starlette选0.37+是因为它原生支持OpenAPI 3.1，Pydantic选2.7+是因为修复了@validator在嵌套模型中的bug，aiocache选0.12+是因为支持Redis集群模式。我们曾因aiocache<0.11不支持Redis Sentinel，在主从切换时缓存全失效，导致数据库被打挂。Poetry的pyproject.toml里还加了Mypy配置：

[tool.mypy] plugins = ["pydantic.mypy"] disallow_untyped_defs = true disallow_incomplete_defs = true warn_return_any = true

这样，def get_user(user_id: str) -> User:如果没写类型注解，CI直接报错。类型安全不是银弹，但它是API稳定的第一道防线。

4.2 目录结构：按能力分层，拒绝“models/views/utils”三件套

传统Django/Flask项目常按技术角色分目录，结果models.py里塞了ORM、DTO、领域模型。我的结构按业务能力分：

src/ ├── api/ # OpenAPI协议定义 │ ├── v1/ │ │ ├── courses.yaml │ │ └── enrollments.yaml ├── core/ # 领域核心逻辑（无框架依赖） │ ├── courses/ │ │ ├── service.py # CourseService，含业务规则 │ │ └── models.py # Course, CourseSummary等纯数据类 │ └── enrollments/ │ ├── service.py │ └── models.py ├── adapters/ # 外部依赖适配器 │ ├── database/ # SQLAlchemy Core，非ORM │ │ ├── repositories.py # Repository接口实现 │ │ └── connection.py # 连接池管理 │ ├── cache/ # aiocache封装 │ │ └── redis.py │ └── external/ # httpx封装的第三方API调用 │ └── sms.py ├── application/ # API应用层（Starlette Router） │ ├── v1/ │ ├── courses.py # 包含路由、中间件、异常处理器 │ └── enrollments.py └── main.py # Uvicorn入口，加载所有组件

重点是core/目录：这里没有任何import starlette或import sqlalchemy，只有纯Python函数和数据类。CourseService.enroll_student()方法签名是def enroll_student(self, student_id: str, course_id: str) -> EnrollmentResult:，不关心数据从哪来、到哪去。这样，当明年要换MongoDB时，只需重写adapters/database/repositories.py，core/courses/service.py一行不用动。我们用pytest写单元测试时，直接from core.courses.service import CourseService，mock掉adapters里的依赖，测试速度极快。

4.3 关键中间件实现：鉴权、限流、审计三件套

所有中间件都用Starlette的BaseHTTPMiddleware实现，保证类型安全：

# adapters/middleware/auth.py class AuthMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): auth_header = request.headers.get("Authorization") if not auth_header or not auth_header.startswith("Bearer "): raise AuthError("Missing or invalid Authorization header") token = auth_header[7:] try: payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"]) request.state.user_id = payload["user_id"] request.state.role = payload["role"] except jwt.ExpiredSignatureError: raise AuthError("Token expired") except jwt.InvalidTokenError: raise AuthError("Invalid token") response = await call_next(request) return response # adapters/middleware/rate_limit.py class RateLimitMiddleware(BaseHTTPMiddleware): def __init__(self, app, limiter: AsyncLimiter): super().__init__(app) self.limiter = limiter async def dispatch(self, request: Request, call_next): key = f"{request.state.user_id}:{request.url.path}" try: await self.limiter.acquire(key) except RateLimitExceededError: raise RateLimitError(f"Rate limit exceeded for {key}") return await call_next(request) # adapters/middleware/audit.py class AuditMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next): start_time = time.time() try: response = await call_next(request) duration_ms = (time.time() - start_time) * 1000 # 写入ClickHouse审计日志 await audit_logger.log( user_id=getattr(request.state, 'user_id', 'anonymous'), endpoint=request.url.path, status_code=response.status_code, duration_ms=round(duration_ms, 2), cache_hit=getattr(response, 'cache_hit', False) ) return response except Exception as e: duration_ms = (time.time() - start_time) * 1000 await audit_logger.log( user_id=getattr(request.state, 'user_id', 'anonymous'), endpoint=request.url.path, status_code=getattr(e, 'status_code', 500), duration_ms=round(duration_ms, 2), cache_hit=False ) raise e

在application/v1/courses.py里组合：

router = Router( routes=[ Route("/courses", endpoint=list_courses, methods=["GET"]), Route("/courses/{course_id}", endpoint=get_course, methods=["GET"]), ], middleware=[ Middleware(AuthMiddleware), Middleware(RateLimitMiddleware, limiter=redis_limiter), Middleware(AuditMiddleware), ] )

这样，每个endpoint自动获得三重防护，且中间件可单独测试。比如测试鉴权中间件：

def test_auth_middleware_missing_header(): app = Starlette(middleware=[Middleware(AuthMiddleware)]) client = TestClient(app) response = client.get("/courses") assert response.status_code == 401 assert response.json()["code"] == "AUTH_ERROR"

4.4 缓存策略：读写分离+版本控制，拒绝“缓存雪崩”

缓存不是加个@cache装饰器就完事。我们的策略是：

• 读缓存：所有GET请求默认走Redis，key格式{service}_{version}_{params_hash}，比如courses_v2_3a7f2b1c（3a7f2b1c是category=math&grade=10的MD5）；
• 写缓存：POST/PUT/DELETE操作后，用Pipeline批量删除相关key，比如enroll_student()成功后，执行redis.delete("courses_v2_*", "enrollments_v1_*")；
• 版本控制：version字段在OpenAPI YAML里定义，每次接口变更（加字段、改逻辑）就升版，旧key自然失效；
• 降级开关：Redis不可用时，自动降级为内存LRU缓存（functools.lru_cache），保证服务不挂。

关键代码在adapters/cache/redis.py：

class RedisCache: def __init__(self, redis_client: Redis): self.client = redis_client async def get(self, key: str) -> Optional[bytes]: try: return await self.client.get(key) except ConnectionError: # 降级到内存缓存 return memory_cache.get(key) async def setex(self, key: str, expire: int, value: bytes): try: await self.client.setex(key, expire, value) except ConnectionError: memory_cache[key] = value async def delete_pattern(self, pattern: str): # Redis不支持async delete pattern，用pipeline模拟 keys = await self.client.keys(pattern) if keys: pipe = self.client.pipeline() for key in keys: pipe.delete(key) await pipe.execute()

我们压测过，当Redis宕机时，内存缓存让QPS从0恢复到1200（仍比Redis慢3倍，但服务可用），而不用缓存的QPS是800——说明降级策略生效。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 问题：Pydantic模型嵌套时，@validator不触发

现象：定义了class EnrollmentRequest(BaseModel): student_id: str; course_id: str，并在student_id上加了@validator，但传{"student_id": 123}时没报错，反而静默转成"123"。

原因：Pydantic V2默认开启coerce_numbers_to_str=True，且@validator只在字段类型匹配时触发。int转str是类型转换，不是校验。

解决：在BaseModel.Config里显式关闭：

class Config: coerce_numbers_to_str = False # 关键！ @validator('student_id') def validate_student_id(cls, v): if not isinstance(v, str): raise ValueError('student_id must be string') return v

实操心得：所有BaseModel子类都继承自APIModel（如3.2节所示），APIModel.Config里已全局关闭coerce_numbers_to_str。我们CI里还加了Mypy检查：if isinstance(v, int): ...这种代码会被标红，强制开发者写if not isinstance(v, str):。

5.2 问题：Uvicorn启动时报Address already in use

现象：uvicorn main:app报错OSError: [Errno 48] Address already in use。

原因：不是端口被占，而是Uvicorn的--reload模式在Mac/Linux下用stat监听文件变化，某些IDE（如PyCharm）的文件索引进程会锁住pyproject.toml，导致Uvicorn无法监听。

解决：三步走：

1. 先lsof -i :8000查端口占用，kill -9 <PID>；
2. 关闭IDE的文件索引（PyCharm：Settings → Advanced Settings → uncheck "Synchronize files on frame activation"）；
3. 启动时加--reload-dir src/ --reload-exclude "pyproject.toml"，避开被锁文件。

实操心得：我们把启动命令写进Makefile：

dev: uvicorn main:app --host 0.0.0.0 --port 8000 --reload --reload-dir src/ --reload-exclude "pyproject.toml,poetry.lock"

新人make dev一键启动，不用记参数。

5.3 问题：异步HTTP调用httpx.AsyncClient报RuntimeError: Event loop is closed

现象：在@app.get里用async with httpx.AsyncClient() as client:调用第三方API，偶尔报Event loop is closed。

原因：Uvicorn的事件循环在请求结束时可能提前关闭，而httpx.AsyncClient的__aexit__还没执行完。

解决：不用async with，改用显式生命周期管理：

# 全局client，复用连接池 http_client = httpx.AsyncClient( timeout=httpx.Timeout(10.0, connect=3.0), limits=httpx.Limits(max_connections=100, max_keepalive_connections=20) ) @app.get("/v1/external-data") async def get_external_data(): try: response = await http_client.get("https://api.example.com/data") response.raise_for_status() return JSONResponse(response.json()) except httpx.HTTPStatusError as e: raise APIError(f"External API returned {e.response.status_code}")

实操心得：http_client在main.py里初始化，app.on_event("startup")里调用http_client.aclose()。我们压测发现，复用client比每次新建快4倍，且100%避免event loop错误。

5.4 问题：Prometheus监控里api_request_duration_seconds_bucket指标暴涨

现象：Grafana里看到api_request_duration_seconds_bucket{le="1.0"}突然从95%掉到30%，大量请求卡在1秒以上。

排查思路：

1. 先查api_error_total{code="DB_UNAVAILABLE"}是否飙升——是，则查数据库连接池；
2. 查redis_client_info{metric="used_memory_rss"}是否接近上限——是，则查缓存key是否没设TTL；
3. 查process_cpu_seconds_total是否突增——是，则定位CPU密集型任务；
4. 最后查http_requests_total{status_code=~"5.."}——如果5xx没涨，但延迟涨，大概率是外部依赖慢。

真实案例：上周延迟暴涨，查下来是http_requests_total{host="sms-gateway.com"}的5xx飙升，但我们的API没报错。原因是短信网关返回了HTTP 200但body里是{"code":500,"msg":"system busy"}。我们立刻在adapters/external/sms.py里加了响应体校验：

if response.json().get("code") != 200: raise ExternalServiceError(f"SMS gateway returned code {response.json().get('code')}")

10分钟内恢复。

5.5 问题：OpenAPI文档里example不显示，Swagger UI一片空白

现象：VS Code里Redocly预览正常，但部署到服务器后Swagger UI里所有字段都是"example": null。

原因：Uvicorn默认不提供OpenAPI JSON，需手动挂载：

# main.py from starlette.staticfiles import StaticFiles from starlette.responses import FileResponse app.mount("/docs", StaticFiles(directory="static/docs"), name="docs") # 关键：提供/openapi.json @app.get("/openapi.json") async def get_openapi(): return JSONResponse(openapi_schema)

实操心得：我们用redoc-cli build openapi/v1/openapi.yaml -o static/docs/index.html生成静态文档，/docs路径直接托管。这样Swagger UI和Redoc都能用，且文档和代码分离，前端可直接CDN加速。

6. 性能压测与上线 checklist：让“Smarter”经得起真实流量考验

6.1 Locust压测脚本：模拟真实用户行为，不止是并发数

不用ab或wrk这种只压单接口的工具。我们用Locust写场景化脚本：

# locustfile.py from locust import HttpUser, task, between import random class StudentUser(HttpUser): wait_time = between(1, 5) # 模拟用户思考时间 @task(3) # 30%权重 def list_courses(self): category = random.choice(["math", "english", "science"]) self.client.get(f"/v1/courses?category={category}&grade={random.randint(1,12)}") @task(1) # 10%权重 def enroll_course(self): # 先获取课程ID resp = self.client.get("/v1/courses?limit=1") if resp.status_code == 200: course_id = resp.json()["data"][0]["id"] # 再报名 self.client.post("/v1/enrollments", json={"course_id": course_id}) @task(0.1) # 1%权重，模拟VIP用户查报告 def get_report(self): self.client.get("/v1/reports/123456")

压测时启动1000个StudentUser，观察三个指标：RPS（每秒请求数）、95%延迟、错误率。我们设定SLA：RPS > 500，95%延迟 < 300ms，错误率 < 0.1%。当不达标时，按顺序检查：1. 数据库连接池是否够（SHOW PROCESSLIST）；2. Redis内存是否溢出（INFO memory）；3. CPU是否100%（top看python进程）；4. 是否有慢SQL（slow_query_log）。

6.2 上线前10项checklist：一份清单，十年经验

每次上线前，我和团队必过这10条，缺一不可：

1. OpenAPI校验：spectral lint openapi/v1/*.yaml无ERROR；
2. 类型检查：mypy src/返回Success: no issues found；
3. 测试覆盖率：pytest --cov=src --cov-report=html，核心core/目录覆盖率>85%；
4. 缓存key检查：grep -r "redis\.set" src/ | grep -v "TTL"，确保所有set都带ex参数；
5. 错误code唯一性：grep -r "code.*=" src/ | cut -d'"' -f2 | sort | uniq -d，确认无重复code；
6. 环境变量检查：grep "os\.environ" src/ | grep -v "default="，确保所有env变量都有default或文档说明；
7. 日志字段完整性：grep "structlog\.get_logger" src/ | xargs -I{} sh -c 'echo {}; {} | grep -E "(request_id|user_id|endpoint)"'，确认关键字段不缺失；
8. 中间件顺序验证：cat src/application/v1/*.py | grep "Middleware("，确认AuthMiddleware在`RateLimit