软件工程启示

前面各章讲的是 mini-shop-server 的具体机制。这些机制背后，是通用的工程思想——离开这个项目它们照样适用。这一页把它们集中成一张清单，供回顾和迁移到自己的项目。

一、架构与组织

项目里的体现	可迁移的工程知识
分层 api / service / dao / models	关注点分离、依赖方向单一（上层只依赖紧邻下层）
红图把「定义路由」和「注册路由」分开	定义与装配分离、依赖倒置
ALL_RP_API_LIST 用配置表达接口组合	配置驱动、声明式装配
v1 / cms 多套接口并存	API 版本化、向后兼容策略
app/__init__.py 统一自动组装	装配器（组合根），把模块连接起来

二、编码实践

• 统一序列化器（hide/append）——数据怎么出境，用一个收口点集中控制，而不是每个 Model 各写 to_dict()。字段「默认不暴露、需要时显式」，敏感字段不易泄漏。
• 统一异常 + 四路 handler——错误分类（业务/HTTP/DB 约束/未知）后统一兜底，业务代码里不散落 try/except。
• 统一校验层——校验收口在入口，业务层只处理已经合法的数据。错误格式统一。
• 统一取参封装（paginate / time_interval / get_request_args）——把高频动作收成工具，接口只留业务。

三、基础设施

• 认证/权限下沉到装饰器——横切关注点（认证、缓存、日志、限流）用装饰器/中间件一次性解决，接口业务零侵入。route_meta 的接口级登记本质是 RBAC。
• @cached 缓存装饰器——路径 + 全部请求参数拼成缓存 key，避免缓存污染。按参数区分缓存是通用做法。
• Swagger 双轨 spec 注入——文档即代码：接口的请求/响应由声明式描述自动生成，参数三种写法体现「怎么设计 API 参数」。
• JSONEncoder 自动格式化时间——规定好时间/日期的统一格式，交给序列化层，接口和前端都不用手动处理。

四、贯穿全局的思想

• 横切关注点（AOP）：认证、日志、异常、文档都是「壳」。把共性抽到壳上，是后端架构观的核心一课。
• 约定优于配置：validate_<字段名> 的命名约定、lock_fileds 的调用时机，都是靠约定而非显式声明。约定降低样板代码，但要求团队遵守。
• 配置驱动 > 硬编码：接口组合、路由挂载、文档顺序都由配置决定，改配置即可裁剪功能，不用改代码。
• 分层换可维护性：分层不是为复杂，而是为「改一处不影响其它」。

---

回想一下各章末的「能带走的思想」，它们都是这张表里知识的展开。学到的不只是 Flask，是任何后端工程通用的取舍。