编码风格和架构规范

发表于 2026-09-3 更新于 2026-09- 3

作者 mdo

12~16 分钟 阅读

针对 ThinkPHP 6 (TP6) 框架 + MVC 模式 + 额外引入服务层 (Service Layer) 的技术栈，要让 crewAI 完美适配你们公司的编码风格和架构规范，我们需要对 Agent 的角色、Prompt 以及生成策略进行定向优化。

在 TP6 中引入服务层，核心目的是为了解耦 Controller 和 Model，让 Controller 只负责接收参数和响应，Model 只负责数据库基础操作，而复杂的业务逻辑、事务控制、第三方接口调用全都沉淀在 Service 层。

下面为您量身定制一套 crewAI 落地方案：

1. 明确三层架构的 Agent 分工

在 crewAI 中，推荐为 TP6 的各个层级配置专属的 Agent，各司其职：

TP6 Model Agent：专门负责生成实体模型、定义字段、关联关系（如 hasMany, belongsTo）。
TP6 Service Agent：核心业务逻辑编写者。处理事务（Db::transaction）、数据转换、调用外部 API。
TP6 Controller Agent：负责接收请求、参数校验（使用 TP6 的 Validate 类）、调用 Service 并返回标准 JSON。
Architecture Reviewer Agent：架构审计员。严格检查是否有业务逻辑漏到了 Controller，或者 Model 里是否写了复杂的业务代码。

2. 定义公司专属的 TP6 代码规范上下文

将你们公司的 TP6 规范总结为结构化文本，作为全局变量注入给所有 Agent：

python

TP6_SERVICE_STYLE_GUIDE = """
1. 目录与命名规范：
   - Controller 路径：app/controller/，命名：Xxx.php (驼峰)
   - Service 路径：app/service/，命名：XxxService.php
   - Model 路径：app/model/，命名：Xxx.php
2. 职责边界（强约束）：
   - Controller：只做参数接收、调用 Validate 类验证、调用 Service 层，禁止写业务逻辑。
   - Service：处理所有业务逻辑。多表操作必须使用 Db::transaction() 闭包控制事务。
   - Model：只定义表名、自动写入时间戳(protected $autoWriteTimestamp = 'datetime')、关联关系，不写业务。
3. 依赖注入 (DI)：
   - 必须使用 TP6 依赖注入机制，在 Controller 的构造函数或方法中注入 Service。
4. 返回规范：
   - 统一使用严格强类型声明 (declare(strict_types=1);)。
   - Controller 必须返回 ThinkPHP 的 json() 对象，格式为：{code: 200, msg: "success", data: []}。
"""

请谨慎使用此类代码。

3. 构建完整的 crewAI 任务流 (代码实现)

以下是完整的 Python 脚本示例。通过多 Agent 协同和链式 Task，确保生成的代码完全符合规范：

python

from crewai import Agent, Task, Crew

# 1. 注入上述定义的规范
# (此处省略上文的 TP6_SERVICE_STYLE_GUIDE 变量)

# 2. 定义各层级 Agent
model_agent = Agent(
    role="ThinkPHP6 模型开发专家",
    goal="生成符合规范的 TP6 Model 类",
    backstory=f"你精通 Eloquent/ThinkPHP ORM。你只负责定义模型属性和关联，严格遵守规范：{TP6_SERVICE_STYLE_GUIDE}",
    verbose=True
)

service_agent = Agent(
    role="PHP 高级业务架构师",
    goal="编写厚重的、包含完整业务逻辑和事务控制的 Service 类",
    backstory=f"你是业务逻辑的核心掌控者。你擅长在 Service 中处理复杂的数据库事务和异常捕获。严格遵守规范：{TP6_SERVICE_STYLE_GUIDE}",
    verbose=True
)

controller_agent = Agent(
    role="ThinkPHP6 控制器专家",
    goal="编写轻量级的 Controller，处理路由响应和参数校验",
    backstory=f"你坚持‘瘦控制器’原则。你只负责调用验证器和 Service，输出标准 JSON。严格遵守规范：{TP6_SERVICE_STYLE_GUIDE}",
    verbose=True
)

reviewer_agent = Agent(
    role="TP6 代码质量总监",
    goal="审计并优化生成的 Controller、Service、Model 代码，确保完美契合公司风格",
    backstory=f"你是一个有代码洁癖的评审员。如果发现 Controller 里有业务逻辑，或者 Service 没有加事务，你会严厉拒绝并要求重写。规范：{TP6_SERVICE_STYLE_GUIDE}",
    verbose=True
)

# 3. 编排链式任务 (Tasks)
requirement = "开发一个‘用户下单并扣减库存’的功能，需要操作用户表、订单表、商品库存表。"

task_model = Task(
    description=f"根据需求：'{requirement}'，生成所需的 TP6 Model 类代码（例如 Order.php, Stock.php）。",
    expected_output="纯 PHP 代码，包含完整的命名空间和严格模式声明。",
    agent=model_agent
)

task_service = Task(
    description=f"参考上一步的模型，根据需求：'{requirement}'，生成 OrderService.php。必须包含创建订单和扣库存的事务处理。",
    expected_output="纯 PHP 代码，包含依赖注入和异常处理(try-catch)。",
    agent=service_agent
)

task_controller = Task(
    description=f"参考前面的 Service，生成 Order.php 控制器。使用依赖注入调用 OrderService，并使用内置的 json() 统一格式返回。",
    expected_output="纯 PHP 代码，严格的瘦控制器模式。",
    agent=controller_agent
)

task_review = Task(
    description="审查前面生成的所有代码(Model, Service, Controller)。检查职责是否分离、命名是否规范、事务是否合规。如果不合规请修正，最后打包输出最终的三个文件代码。",
    expected_output="格式优雅、完全符合公司规范的完整 TP6 三层架构代码。使用 Markdown 分块展示。",
    agent=reviewer_agent
)

# 4. 组装并启动
crew = Crew(
    agents=[model_agent, service_agent, controller_agent, reviewer_agent],
    tasks=[task_model, task_service, task_controller, task_review],
    verbose=True
)

result = crew.kickoff()
print(result)

请谨慎使用此类代码。

4. 针对 TP6+Service 的避坑与进阶技巧

提供 Few-Shot（示例模版）：在 Task 的 description 里，最好贴一段你们公司现有的、写得最好的 BaseService 或某个标准 Service 作为“样板戏”，AI 的模仿能力会达到惊人的准确度。
验证器（Validate）联动：如果公司规范要求每个接口必须有独立的验证器类（如 app\validate\User.php），可以再加一个 Validate Agent，让 Controller Agent 去读取验证器的规则，从而避免在 Controller 里面写一堆 request()->param() 的硬编码校验。

为了让代码生成更精准，我们可以进一步细化。请问：

你们的 Service 层是否有一个基类（例如 extends BaseService）？如果有，基类提供了哪些常用方法（如统一的单例调用或异常处理）？
你们在 Service 中处理错误返回时，习惯用什么方式？（例如：直接 throw 自定义异常、还是返回 BaseResponse 对象，亦或是返回 bool/array？）

技术

许可协议: CC BY 4.0