title: 第一个接口：控制器、蓝图、依赖注入与 requirements.txt
lecture: 2-1-6
chapter: 2
section: 1
series: AI Agent 全栈开发工程师学习笔记
tags: [Flask, 蓝图, injector, pipreqs]
第一个接口：控制器、蓝图、依赖注入与 requirements.txt
起点：立一个只会回 pong 的接口，但把它立在规范上
/ping → {"ping": "pong"}是这套后端里最没用的接口。它的价值全在"走完全程"：请求进来 → 路由表命中 → 蓝图分发 → 控制器处理 → 返回 JSON。这条链路一旦跑通，后面每个新接口都只是往同样的三个位置各加几行。
顺便，这一步还会暴露一个真实问题：装完包之后pip freeze倒出来的依赖清单里，一大半项目根本没用到。
装两个包
pipinstallflask pipinstallinjector装完在 PyCharm 的解释器页面能看到flask 3.0.2和它拖进来的Jinja2 / click / itsdangerous / werkzeug / blinker / MarkupSafe。这两个包就是整个骨架阶段的全部外部依赖。
控制器：app/internal/handler/app_handler.py
在internal/handler/下新建app_handler.py，定义AppHandler类（文档注释写"应用控制器"），里面一个ping方法，返回一个字典：
classAppHandler:"""应用控制器"""defping(self):return{"ping":"pong"}返回字典这个动作本身就是响应。Flask 看到视图函数返回dict，会自动序列化成 JSON 并带上Content-Type: application/json，不需要手写jsonify。这是后面所有接口统一响应结构的起点。
导出控制器：app/internal/handler/__init__.py
from.app_handlerimportAppHandler __all__=["AppHandler"]__all__是 Python 的魔术变量，一个字符串列表，声明这个模块对外导出哪些名字。配好之后，别的模块写from internal.handler import AppHandler就行，不用关心AppHandler到底躺在handler/下的哪个文件里。
这一步不是装饰。控制器文件会越来越多（account_handler.py、知识库控制器、工具控制器……），把导入路径收在包的__init__.py里，将来拆分或重命名文件时，改动只发生在一处。
路由：app/internal/router/router.py
路由的工作是把 URL 和控制器方法绑定。Flask 里这件事通过**蓝图（Blueprint）**做——蓝图是一组路由的集合，便于按功能模块管理，比如前台和后台用不同的 URL 前缀。
注册分三步：
