架构总览

mini-shop-server 采用 分层 + AOP（面向切面） 架构。这是全项目的主线，理解了它，就能读懂大部分代码。

分层调用链

浏览器 / 小程序
      │ HTTP
      ▼
┌─────────────────────────────────────────────┐
│  接口层  app/api/v1 · app/api/cms           │  路由 + 装饰器壳（认证 / 文档 / 日志）
├─────────────────────────────────────────────┤
│  校验层  app/validators                     │  参数「体检」，不合法拦在门口
├─────────────────────────────────────────────┤
│  业务层  app/service                        │  下单、支付、登录等真实业务
├─────────────────────────────────────────────┤
│  数据层  app/dao → app/models               │  查询封装 → ORM 表映射
├─────────────────────────────────────────────┤
│  持久层  PostgreSQL                         │  真实存储
└─────────────────────────────────────────────┘

每层只依赖下一层，不越级调用。改动数据库（models/dao）不影响 service；加认证只动装饰器，不动业务函数。

两个核心设计

1. 红图（Redprint）—— 更灵活的路由组织

比 Flask 原生蓝图更灵活：先「收集」路由，再统一「注册」，配合 RedprintAssigner 自由组合到对应版本蓝图。

详见：红图 Redprint

2. AOP —— 横切关注点抽离

认证、异常、日志、文档都被设计成「装饰器壳」，从业务函数里抽出。业务函数只关心数据。

@api.route(...)                # 路由壳
@api.doc(...)                  # 文档壳
@auth.login_required           # 认证壳
def business(): ...            # 纯业务

详见：一次请求的生命周期、统一异常与响应格式

双端接口

版本	前缀	服务对象	入口
v1	/v1/	小程序用户（C 端）	app/api/v1
cms	/cms/	后台管理（B 端）	app/api/cms

技术栈

Flask 2.0 · SQLAlchemy（ORM）· flasgger（Swagger）· WTForms（校验）· uv（依赖管理）

• 从 入门指南 开始学习
• 或看 API 参考