# 代码规范

<cite>
**本文引用的文件**   
- [AGENTS.MD](file://AGENTS.MD)
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [.example.env](file://.example.env)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/themes/admin_default/admin/route/index.html](file://public/themes/admin_default/admin/route/index.html)
- [public/themes/admin_default/admin/route/add.html](file://public/themes/admin_default/admin/route/add.html)
- [public/themes/admin_default/admin/route/edit.html](file://public/themes/admin_default/admin/route/edit.html)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心规范](#核心规范)
4. [架构总览](#架构总览)
5. [组件详解](#组件详解)
6. [依赖关系分析](#依赖关系分析)
7. [性能与一致性建议](#性能与一致性建议)
8. [故障排查与常见问题](#故障排查与常见问题)
9. [结论](#结论)
10. [附录：工具与自动化](#附录工具与自动化)

## 简介
本文件系统性整理 ThinkCMF 的代码规范，覆盖命名规范、目录与文件命名、注释规范、数据库命名、URL 与模板变量规范，并给出与仓库现有实现相印证的证据来源，帮助团队在开发中保持一致性和可维护性。

## 项目结构
- ThinkCMF 采用多应用架构，包含前台应用、API 应用、插件与主题等模块。入口文件分别指向不同应用空间，便于区分 API 与前台流量。
- 自动加载通过 PSR-4 配置，将命名空间映射到具体目录，确保类名与文件路径一致。

```mermaid
graph TB
A["public/index.php<br/>前台入口"] --> B["App()<br/>HTTP应用"]
C["public/api.php<br/>API入口"] --> D["App()<br/>HTTP应用"]
E["composer.json<br/>PSR-4自动加载"] --> F["命名空间映射<br/>app/ → api/ → plugins/ → themes/"]
G["AGENTS.MD<br/>开发规范章节"] --> H["命名规范/数据库规范/注释规范"]
```

**图表来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)
- [AGENTS.MD:448-509](file://AGENTS.MD#L448-L509)

**章节来源**
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)
- [AGENTS.MD:78-134](file://AGENTS.MD#L78-L134)

## 核心规范

### 命名规范
- 目录与文件
  - 目录：小写+下划线
  - 类文件：驼峰法（首字母大写）
  - 其他文件：小写+下划线
  - 后缀：统一 .php
- 类与函数
  - 类名：驼峰法（首字母大写）
  - 函数：小写+下划线
  - 方法：驼峰法（首字母小写）
  - 属性：驼峰法（首字母小写）
- 常量与配置
  - 常量：大写+下划线
  - 配置：小写+下划线
  - 环境变量：大写+下划线
- 数据库
  - 表名：小写+下划线
  - 字段名：小写+下划线
- URL 规范
  - 除 API 的 URL，其他 URL 不能以 api/ 开头
- 模板变量
  - assign 变量：小写+下划线
  - 变量名称：必须与变量相同
- 表单 name
  - 表单 name：小写+下划线

以上规范均来自项目开发规范文档。

**章节来源**
- [AGENTS.MD:454-494](file://AGENTS.MD#L454-L494)

### 注释规范
- 默认使用中文进行代码注释
- 代码定义使用英文（变量、函数、类名等）
- 添加函数级注释
- 错误信息优先使用中文

**章节来源**
- [AGENTS.MD:502-507](file://AGENTS.MD#L502-L507)

### 数据库命名规范
- 表名：小写+下划线；默认表前缀 cmf_；非核心应用表带应用前缀（如 portal_）；插件表带插件前缀（如 plugin_demo_）
- 字段名：小写+下划线
- 通用字段：id、create_time、update_time、delete_time、status、list_order、remark、description
- 布尔字段：以 is_/has_/exist_/can_ 开头
- 文件相关字段：image、thumbnail、photos
- 用户相关字段：除 user 表外，其他表使用 user_id 代表用户 ID
- 扩展字段：more（text 或 longtext）
- 层级关系字段：parent_id

**章节来源**
- [AGENTS.MD:367-411](file://AGENTS.MD#L367-L411)

### URL 与模板变量规范
- URL 规范：除 API 的 URL，其他 URL 不能以 api/ 开头
- 模板变量：assign 变量使用小写+下划线，且变量名称必须与赋值的变量名一致

**章节来源**
- [AGENTS.MD:484-491](file://AGENTS.MD#L484-L491)

## 架构总览
ThinkCMF 采用多应用架构，入口文件分别指向前台与 API 应用，结合 PSR-4 自动加载，确保类名与文件路径一致。Swagger 插件作为示例展示了基于注解的 API 文档生成能力。

```mermaid
graph TB
subgraph "入口与应用"
IDX["public/index.php<br/>前台入口"] --> APPNS["命名空间 app\\"]
APIP["public/api.php<br/>API入口"] --> APINS["命名空间 api\\"]
end
subgraph "自动加载"
CJ["composer.json<br/>PSR-4"] --> MAP1["app\\ → app/"]
CJ --> MAP2["api\\ → api/"]
CJ --> MAP3["plugins\\ → public/plugins/"]
CJ --> MAP4["themes\\ → public/themes/"]
end
subgraph "示例插件"
SWP["public/plugins/swagger/SwaggerPlugin.php<br/>插件主类"] --> SWNS["命名空间 plugins\\swagger\\"]
end
APPNS --> MAP1
APINS --> MAP2
SWP --> SWNS
```

**图表来源**
- [public/index.php:10-28](file://public/index.php#L10-L28)
- [public/api.php:27-30](file://public/api.php#L27-L30)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/SwaggerPlugin.php:10-17](file://public/plugins/swagger/SwaggerPlugin.php#L10-L17)

**章节来源**
- [public/index.php:10-30](file://public/index.php#L10-L30)
- [public/api.php:27-36](file://public/api.php#L27-L36)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/SwaggerPlugin.php:10-17](file://public/plugins/swagger/SwaggerPlugin.php#L10-L17)

## 组件详解

### 命名与文件组织
- 目录命名：小写+下划线（如 themes/admin_default）
- 类文件：驼峰法（如 SwaggerPlugin.php）
- 其他文件：小写+下划线（如 config.php）
- 后缀：统一 .php

这些约定在开发规范文档中有明确说明。

**章节来源**
- [AGENTS.MD:454-459](file://AGENTS.MD#L454-L459)

### 类与函数命名
- 类名：驼峰法（首字母大写）
- 函数：小写+下划线
- 方法：驼峰法（首字母小写）
- 属性：驼峰法（首字母小写）

示例参考插件主类 SwaggerPlugin 的类名与方法命名。

**章节来源**
- [AGENTS.MD:460-469](file://AGENTS.MD#L460-L469)
- [public/plugins/swagger/SwaggerPlugin.php:17-48](file://public/plugins/swagger/SwaggerPlugin.php#L17-L48)

### 常量与配置
- 常量：大写+下划线（如 APP_PATH、CMF_ROOT）
- 配置：小写+下划线（如 url_route_on、database_hostname）
- 环境变量：大写+下划线（如 APP_DEBUG、DATABASE_HOSTNAME）

示例参考入口文件中的常量定义与 .env 示例。

**章节来源**
- [AGENTS.MD:470-477](file://AGENTS.MD#L470-L477)
- [public/index.php:15-25](file://public/index.php#L15-L25)
- [.example.env:1-1](file://.example.env#L1-L1)

### 数据库命名
- 表名：小写+下划线；默认前缀 cmf_；应用前缀 portal_；插件前缀 plugin_demo_
- 字段名：小写+下划线
- 通用字段与布尔字段命名约定清晰

**章节来源**
- [AGENTS.MD:367-411](file://AGENTS.MD#L367-L411)

### URL 与模板变量
- URL 规范：除 API 的 URL，其他 URL 不能以 api/ 开头
- 模板变量：assign 变量使用小写+下划线，变量名与赋值变量一致

模板示例展示了后台路由管理页面的表单字段命名与变量使用。

**章节来源**
- [AGENTS.MD:484-491](file://AGENTS.MD#L484-L491)
- [public/themes/admin_default/admin/route/index.html:12-32](file://public/themes/admin_default/admin/route/index.html#L12-L32)
- [public/themes/admin_default/admin/route/add.html:12-29](file://public/themes/admin_default/admin/route/add.html#L12-L29)
- [public/themes/admin_default/admin/route/edit.html:15-29](file://public/themes/admin_default/admin/route/edit.html#L15-L29)

### 注释与错误信息
- 默认使用中文注释
- 代码定义使用英文
- 添加函数级注释
- 错误信息优先使用中文

**章节来源**
- [AGENTS.MD:502-507](file://AGENTS.MD#L502-L507)

## 依赖关系分析
- 入口文件通过常量定义应用根目录与应用路径，确保运行时定位正确。
- composer.json 的 PSR-4 自动加载配置将命名空间映射到具体目录，保证类名与文件路径一致。
- Swagger 插件示例展示了插件主类的命名与命名空间组织方式。

```mermaid
graph LR
IDX["public/index.php<br/>定义常量"] --> RUNTIME["运行时定位"]
APIP["public/api.php<br/>定义常量"] --> RUNTIME
CJ["composer.json<br/>PSR-4映射"] --> AUTOLOAD["自动加载"]
SWP["public/plugins/swagger/SwaggerPlugin.php<br/>插件主类"] --> NAMESPACE["命名空间 plugins\\swagger\\"]
```

**图表来源**
- [public/index.php:15-25](file://public/index.php#L15-L25)
- [public/api.php:15-25](file://public/api.php#L15-L25)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/SwaggerPlugin.php:10-17](file://public/plugins/swagger/SwaggerPlugin.php#L10-L17)

**章节来源**
- [public/index.php:15-25](file://public/index.php#L15-L25)
- [public/api.php:15-25](file://public/api.php#L15-L25)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/SwaggerPlugin.php:10-17](file://public/plugins/swagger/SwaggerPlugin.php#L10-L17)

## 性能与一致性建议
- 保持命名与文件组织的一致性，有助于 IDE 自动补全与静态分析工具识别。
- 在模板中严格使用小写+下划线的变量命名，减少模板解析歧义。
- 遵循注释规范，统一使用中文注释与英文定义，提升可读性与协作效率。

[本节为通用建议，无需特定文件引用]

## 故障排查与常见问题
- 若出现类找不到或自动加载失败，检查 composer.json 的 PSR-4 配置与类文件路径是否一致。
- 若 URL 访问异常，确认是否违反“除 API 的 URL，其他 URL 不能以 api/ 开头”的规范。
- 若模板变量无法渲染，检查 assign 变量是否使用小写+下划线且变量名一致。

**章节来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [AGENTS.MD:484-491](file://AGENTS.MD#L484-L491)

## 结论
ThinkCMF 的代码规范围绕命名、注释、数据库与 URL/模板变量等方面建立了清晰的约定，并通过入口文件与 composer.json 的自动加载配置得以落地。遵循上述规范可显著提升代码一致性、可读性与可维护性。

[本节为总结，无需特定文件引用]

## 附录：工具与自动化
- 入口文件与环境配置
  - 入口文件定义常量并加载 vendor 自动加载器，执行 HTTP 应用并响应。
  - .env 示例展示了环境变量的大写+下划线命名方式。
- API 与前台入口
  - public/index.php 对应前台应用命名空间 app\。
  - public/api.php 对应 API 应用命名空间 api\。
- Swagger 插件
  - 插件主类 SwaggerPlugin 展示了插件命名与命名空间组织方式。

**章节来源**
- [public/index.php:10-36](file://public/index.php#L10-L36)
- [public/api.php:27-36](file://public/api.php#L27-L36)
- [.example.env:1-1](file://.example.env#L1-L1)
- [public/plugins/swagger/SwaggerPlugin.php:10-17](file://public/plugins/swagger/SwaggerPlugin.php#L10-L17)