签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,30 +1,42 @@
 # 12.6 后端编码规范

 :::tip 概述
-本节定义后端 PHP 代码的编写规范，包括 Model、Logic、Controller、Validate 各层的命名和结构规范，确保团队代码风格统一。
+本节定义后端 PHP 代码的编写规范，包括 Model、Service、Controller、FormRequest 各层的命名和结构规范，确保团队代码风格统一。代码风格以 Laravel Pint（`./vendor/bin/pint`）为准。
 :::

 ## Model 层规范

 ```php
-// 继承 BaseModel
-class Example extends BaseModel
+// 继承 Eloquent Model（app/Models/Example.php）
+class Example extends Model
 {
+    // 软删除（is_delete）+ 审计字段（create_user/create_time/update_user/update_time）
+    use HasAuditColumns, SoftDeletesByFlag;
+
    /**
-     * 对应数据库表名（不含前缀）
+     * 对应数据库表名
     *
     * @var string
     */
-    protected $name = 'example';
+    protected $table = 'example';
+
+    /**
+     * 批量赋值白名单
+     *
+     * @var array<int, string>
+     */
+    protected $fillable = ['name', 'avatar', 'type', 'status', 'sort'];
 }
 ```

-## Logic 层规范
+## Service 层规范

 ```php
-// 系统共享模块继承 BaseLogic
-class ExampleLogic extends BaseLogic
+// 系统共享模块继承 BaseService
+class ExampleService extends BaseService
 {
+    use HasCrudOperations, HasQueryScopes, HasSerializeMaps;
+
    /**
     * 关联的模型类
     *
@@ -58,63 +70,65 @@ class ExampleLogic extends BaseLogic
    }
 }

-// 租户模块继承 BaseTenantLogic
-class UserLogic extends BaseTenantLogic { ... }
+// 租户模块继承 BaseTenantService（含 tenant_id 的业务表）
+class UserService extends BaseTenantService { ... }
 ```

+可用生命周期钩子（`HasCrudOperations`）：`beforeAdd` / `afterAdd` / `beforeUpdate` / `afterUpdate` / `beforeDelete` / `afterDelete` / `beforeBatchDelete` / `afterBatchDelete` / `afterDetail` / `afterPageList`。
+
 ## Controller 层规范

 ```php
-class ExampleController extends BaseController
+class ExampleController extends Controller
 {
-    protected ExampleLogic $logic;
-
-    protected function initialize(): void
-    {
-        $this->logic = new ExampleLogic();
-    }
+    // 构造函数注入 Service（不在 initialize 中手动 new）
+    public function __construct(protected ExampleService $exampleService) {}

    // 使用注解
-    #[Log('模块-操作', Log::TYPE_ADD)]
-    #[Permission('sys:example:add', '添加')]
-    public function add(): Json
+    #[OperationLog('示例管理-新增', OperationLog::TYPE_ADD)]
+    #[Permission('sys:example:add', '新增示例')]
+    public function add(ExampleRequest $request): JsonResponse
    {
-        return parent::_add($this->logic, $this->getJsonBody());
+        return $this->_add($this->exampleService, $request->validated());
    }
 }
 ```

-## Validate 层规范
+:::tip 瘦控制器
+Controller 只做三件事：参数获取（FormRequest）→ 调用 Service → 返回 JSON。业务规则一律写在 Service，不在控制器写 if/else 业务判断。
+:::
+
+## FormRequest 层规范

 ```php
-class ExampleValidate extends Validate
+class ExampleRequest extends BaseRequest
 {
-    protected $rule = [
-        'name' => 'require',
-        'categoryId' => 'require',  // ✅ 驼峰命名
-        // 'category_id' => 'require',  // ❌ 禁止下划线
-    ];
+    public function rules(): array
+    {
+        return [
+            'name' => 'required|string|max:255',       // ✅ 驼峰命名
+            'categoryId' => 'required|integer',         // ✅ 驼峰命名
+            // 'category_id' => 'required',             // ❌ 禁止下划线
+        ];
+    }

-    protected $message = [
-        'name.require' => '名称不能为空',
-        'categoryId.require' => '分类不能为空',
-    ];
-
-    protected $scene = [
-        'add' => ['name', 'categoryId'],
-        'update' => ['name'],
-    ];
+    public function messages(): array
+    {
+        return [
+            'name.required' => '名称不能为空',
+            'categoryId.required' => '分类不能为空',
+        ];
+    }
 }
 ```

 :::warning 字段名必须使用驼峰
-Validate 中的字段名必须使用 camelCase（驼峰），与前端传参一致。
-因为校验发生在 `BaseLogic::beforeAdd` 之后、`array_camel_to_snake` 转换之前，
-此时数据键名还是驼峰形式。使用下划线会导致校验规则匹配不到字段。
+FormRequest 中的字段名必须使用 camelCase（驼峰），与前端传参一致——使用下划线会导致校验规则匹配不到字段。控制器以 `validated()` 取数原样传递，键名转换由 Service 写入入口（doAdd/doUpdate）统一完成。
 :::

 ## 注解规范

- 所有写操作（POST/PUT/DELETE）必须标注 `#[Log]`
+- 所有写操作（POST/PUT/DELETE）必须标注 `#[OperationLog('模块-操作', OperationLog::TYPE_XXX)]`
 - 所有需要权限控制的接口必须标注 `#[Permission]`
- 权限码格式：`sys:{模块名}:{操作}`
+- 权限码格式：`sys:{模块名}:{操作}`
+- 演示环境放行的只读接口标注 `#[DemoAllow]`