Python Connexion 规范优先自动校验请求的Web框架

多数团队写 API 的顺序是反的：先写代码，再补文档，结果文档永远滞后、缺失细节，还混着实现逻辑。调用方拿到一份和实际行为对不上的接口文档，联调成本高得离谱。规范优先（spec-first）的理念喊了很多年，缺的是一个让「先写规范」不增加额外负担的框架。

Connexion 就是这个方向的代表作：你用 OpenAPI（或 Swagger）规范描述 API，想写多细写多细，框架保证代码的实际行为和规范完全一致。这个项目在 Python 生态里已经营业多年，最新 3.x 重写了异步架构，GitHub 上 4600 多 Star。

项目基本信息

一、项目介绍

Connexion 是一个让规范优先、API 优先开发变简单的现代 Python Web 框架。工作方式与传统框架相反：你先写 OpenAPI 规范文件，Connexion 读取它，自动完成到 Python 函数的映射，并保证运行时行为与规范一致。

基于规范，框架自动提供这些能力：路由自动注册，不需要 @route 装饰器；请求与响应校验，覆盖头、参数和请求体，不合规范的请求直接被拦下；参数解析与注入，函数签名里直接拿到转换好的参数，不用碰 request 对象；响应序列化，函数直接返回普通 Python 对象；认证与业务逻辑分离；附带一个可交互试用的 Swagger UI 控制台；全维度可插拔。

它既可以独立成应用，也能作为中间件包在任何 ASGI 或 WSGI 兼容框架外面。独立应用有 AsyncApp（原生异步，新项目首选）和 FlaskApp（沿用 Flask 生态）两种选择。3.0 版本是近年的一次大重写，全面拥抱 ASGI 异步。

二、核心优势

第一，文档即契约。规范文件就是唯一事实来源，多团队协作时把文档发给依赖方，行为由框架强制保证，不会出现「文档说有这个字段」的扯皮。

第二，校验免费获得。入参出参的校验规则写在规范里，框架自动执行，业务代码里不再散落手写校验。

第三，迁移成本低。FlaskApp 模式让 2.x 用户平滑过渡，也能直接包住既有 Flask 应用渐进引入。

第四，开发体验好。CLI 可以直接运行和 Mock 规范，后端没写完前端就能照着 Mock 联调。

三、适用场景

第一类是多团队共享 API 平台：规范先行的契约开发模式能显著降低跨团队联调成本。

第二类是微服务接口层：每个服务的边界用 OpenAPI 严格定义，配合校验把非法请求挡在业务代码之外。

第三类是给既有 Flask/ASGI 应用补规范：以中间件方式接入，存量代码不用推倒重来。

四、安装教程

pip 安装核心包：

pip install connexion

按需安装扩展解锁附加功能：

pip install connexion[swagger-ui]
pip install connexion[swagger-ui,uvicorn]
pip install connexion[flask]

swagger-ui 提供交互控制台，uvicorn 让开发时可以直接 app.run() 启动而不依赖外部 ASGI 服务器，flask 启用 FlaskApp 兼容生态。

常见报错：装完后运行报 ModuleNotFoundError: flask，说明用了 FlaskApp 但没装 flask 扩展；Swagger UI 打不开同理检查 swagger-ui 扩展；Python 版本过低导致安装失败，Connexion 3.x 要求较新的 Python 3.x，升级解释器即可。

五、使用示例

新建一个最简应用：

from connexion import AsyncApp

app = AsyncApp(__name__)

配套的 OpenAPI 规范文件 openapi.yaml 里定义端点、参数与响应结构，paths 段落指向处理函数：

paths:
  /greeting/{name}:
    get:
      operationId: app.greeting
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: ok

对应的 Python 函数直接按名字拿参数：

def greeting(name: str) -> dict:
    return {"msg": f"Hello {name}"}

启动开发服务器：

connexion run openapi.yaml

访问 /greeting/hei 返回 {"msg": "Hello hei"}；请求缺了 name 参数，框架直接返回 400 校验错误，根本不会进你的函数。浏览器打开 Swagger UI 还能在线试用每个端点。

六、常见问题

和 FastAPI 怎么选？FastAPI 是代码优先加装饰器风格，Connexion 是规范优先，规范文件是交付物本身；已有 OpenAPI 契约或契约驱动的团队选 Connexion 更顺。

性能如何？基于 ASGI 异步架构，常规 Web 服务的负载没有问题，极致性能场景自行压测。

支持 FastAPI 式的自动文档吗？内置 Swagger UI 控制台，文档就是你的规范文件。

七、总结

Connexion 把「文档可信」这件事从纪律问题变成了架构问题：规范是唯一事实来源，框架负责让代码服从它。对契约敏感的团队接口开发，它仍然是 Python 生态里最纯粹的规范优先实现。