python-cola-skill

Python COLA Architecture Guide - Adapting Alibaba's COLA Clean Layered Architecture to Python/Flask/FastAPI projects. It is used for DDD layered architecture design, code structure standards, and application architecture refactoring in Python backends. Triggers: Python DDD, Flask architecture, FastAPI architecture, Python layered architecture, clean architecture, hexagonal architecture, onion architecture, COLA, code layering, module division, Gateway pattern, Repository pattern, CQRS, architectural refactoring, separation of concerns. Automatically applies the COLA directory structure and naming conventions when creating Python files.

Python COLA 架构

COLA = Clean Object-Oriented and Layered Architecture（整洁面向对象分层架构）

分层架构

Adapter → Application → Domain ← Infrastructure
                    ↘      ↙
                     Client

| 层 | 职责 | Python 实现 | |---|------|------------| | Adapter | 接收外部请求 | Flask Blueprint / FastAPI Router | | Application | 用例编排 | Service, CmdExe, QryExe | | Domain | 核心业务逻辑 | Entity, ValueObject, Gateway 接口 | | Infrastructure | 技术实现 | Gateway 实现, SQLAlchemy | | Client | DTO 定义 | Command, Query, CO |

目录结构

project/
├── adapter/routes/           # Flask Blueprint
├── application/
│   ├── command/              # *_cmd_exe.py
│   ├── query/                # *_qry_exe.py
│   └── service/              # *_service.py
├── client/
│   ├── api/                  # *_service_i.py (Protocol)
│   └── dto/
│       ├── command/          # *_cmd.py
│       ├── query/            # *_qry.py
│       └── co/               # *_co.py
├── domain/
│   ├── {aggregate}/          # entity.py, value_object.py
│   └── gateway/              # *_gateway.py (ABC)
├── infrastructure/
│   ├── gateway_impl/         # *_gateway_impl.py
│   ├── convertor/            # *_convertor.py
│   └── repository/           # models.py
└── app.py

命名规范

| 类型 | 后缀 | 位置 | |------|------|------| | 命令 | _cmd | client/dto/command | | 查询 | _qry | client/dto/query | | 命令执行器 | _cmd_exe | application/command | | 查询执行器 | _qry_exe | application/query | | 客户端对象 | _co | client/dto/co | | 服务接口 | _service_i | client/api | | 服务实现 | _service | application/service | | 网关接口 | _gateway | domain/gateway | | 网关实现 | _gateway_impl | infrastructure/gateway_impl | | 转换器 | _convertor | infrastructure/convertor |

核心原则

Domain 层不依赖任何层（纯 Python，无框架依赖）
Infrastructure 实现 Domain 定义的 Gateway 接口
Client 层被所有层依赖（DTO 定义）

代码模板

详细代码示例请参考：

Response 和 DTO: references/dto.md
Service 和执行器: references/service.md
Gateway 模式: references/gateway.md
完整示例: references/example.md

重构检查清单

创建 adapter/application/client/domain/infrastructure 包
定义 Response、Command、Query、CO 类
创建 CmdExe/QryExe 执行器和 Service
定义 Gateway 接口（ABC）和实现
创建 Convertor 转换器
迁移路由到 adapter/routes

Python vs Java 对照

| Java | Python | |------|--------| | interface | Protocol 或 ABC | | @Autowired | 构造函数注入 | | @CatchAndLog | @catch_and_log 装饰器 | | @Data | @dataclass | | @RestController | Flask Blueprint |