120 lines
2.6 KiB
Markdown
120 lines
2.6 KiB
Markdown
# 12.6 后端编码规范
|
|
|
|
:::tip 概述
|
|
本节定义后端 PHP 代码的编写规范，包括 Model、Logic、Controller、Validate 各层的命名和结构规范，确保团队代码风格统一。
|
|
:::
|
|
|
|
## Model 层规范
|
|
|
|
```php
|
|
// 继承 BaseModel
|
|
class Example extends BaseModel
|
|
{
|
|
/**
|
|
* 对应数据库表名（不含前缀）
|
|
*
|
|
* @var string
|
|
*/
|
|
protected $name = 'example';
|
|
}
|
|
```
|
|
|
|
## Logic 层规范
|
|
|
|
```php
|
|
// 系统共享模块继承 BaseLogic
|
|
class ExampleLogic extends BaseLogic
|
|
{
|
|
/**
|
|
* 关联的模型类
|
|
*
|
|
* @var string
|
|
*/
|
|
protected string $modelClass = Example::class;
|
|
|
|
/**
|
|
* LIKE 模糊匹配字段
|
|
*
|
|
* @var array
|
|
*/
|
|
protected array $pageLikeFields = ['name'];
|
|
|
|
/**
|
|
* 精确匹配字段
|
|
*
|
|
* @var array
|
|
*/
|
|
protected array $pageEqFields = ['status'];
|
|
|
|
/**
|
|
* 新增前处理
|
|
*
|
|
* @param array $data 待新增的数据
|
|
* @return array 处理后的数据
|
|
*/
|
|
protected function beforeAdd(array $data): array
|
|
{
|
|
return $data;
|
|
}
|
|
}
|
|
|
|
// 租户模块继承 BaseTenantLogic
|
|
class UserLogic extends BaseTenantLogic { ... }
|
|
```
|
|
|
|
## Controller 层规范
|
|
|
|
```php
|
|
class ExampleController extends BaseController
|
|
{
|
|
protected ExampleLogic $logic;
|
|
|
|
protected function initialize(): void
|
|
{
|
|
$this->logic = new ExampleLogic();
|
|
}
|
|
|
|
// 使用注解
|
|
#[Log('模块-操作', Log::TYPE_ADD)]
|
|
#[Permission('sys:example:add', '添加')]
|
|
public function add(): Json
|
|
{
|
|
return parent::_add($this->logic, $this->getJsonBody());
|
|
}
|
|
}
|
|
```
|
|
|
|
## Validate 层规范
|
|
|
|
```php
|
|
class ExampleValidate extends Validate
|
|
{
|
|
protected $rule = [
|
|
'name' => 'require',
|
|
'categoryId' => 'require', // ✅ 驼峰命名
|
|
// 'category_id' => 'require', // ❌ 禁止下划线
|
|
];
|
|
|
|
protected $message = [
|
|
'name.require' => '名称不能为空',
|
|
'categoryId.require' => '分类不能为空',
|
|
];
|
|
|
|
protected $scene = [
|
|
'add' => ['name', 'categoryId'],
|
|
'update' => ['name'],
|
|
];
|
|
}
|
|
```
|
|
|
|
:::warning 字段名必须使用驼峰
|
|
Validate 中的字段名必须使用 camelCase（驼峰），与前端传参一致。
|
|
因为校验发生在 `BaseLogic::beforeAdd` 之后、`array_camel_to_snake` 转换之前，
|
|
此时数据键名还是驼峰形式。使用下划线会导致校验规则匹配不到字段。
|
|
:::
|
|
|
|
## 注解规范
|
|
|
|
- 所有写操作（POST/PUT/DELETE）必须标注 `#[Log]`
|
|
- 所有需要权限控制的接口必须标注 `#[Permission]`
|
|
- 权限码格式：`sys:{模块名}:{操作}` |