CatchAdmin 专业版文档

主题

规范 ​

CatchAdmin 是一款基于现代化技术栈构建的前后端分离框架，采用模块化架构设计。为了确保代码质量和项目的长期可维护性，制定了一套完整的开发规范体系。

这套规范体系具有以下特点：

  • 标准化：严格遵循社区公认的编码标准，具有广泛的适用性
  • 模块化：支持功能模块的独立开发和维护，提高代码复用性
  • 可维护性：通过统一的规范降低代码维护成本和团队协作难度

所有规范均基于行业最佳实践和社区标准制定，而非个人偏好，确保了规范的权威性和普适性。

代码规范 ​

PHP 代码规范 ​

项目严格遵循 PSR-12 编码标准，这是 PHP 社区广泛认可的代码风格规范，确保代码的一致性和可读性。通过统一的编码风格，团队成员可以更容易地理解和维护彼此的代码。

代码格式化工具：

项目集成了 Laravel Pint 作为代码格式化工具，它基于 PHP CS Fixer 构建，专为 Laravel 项目优化。配置文件 pint.json 位于项目根目录：

json
{
  "preset": "psr12",
  "rules": {
    "braces": false
  },
  "exclude": ["database"],
  "notName": ["server.php"]
}

配置说明：

  • preset: 使用 PSR-12 预设规则
  • rules.braces: 禁用大括号格式化规则，保持 Laravel 风格
  • exclude: 排除 database 目录，避免格式化迁移文件
  • notName: 排除特定文件名

IDE 集成：

建议在 PHPStorm 中配置自动格式化，在保存文件时自动应用代码规范。也可以使用命令行进行批量格式化：

shell
composer pint

该命令会格式化项目中所有符合条件的 PHP 文件，确保代码风格的一致性。

前端代码规范 ​

前端采用现代化的 Vue 3 + TypeScript 技术栈，项目文件独立存放在 web 目录中。TypeScript 提供了强类型支持，显著提高了代码的健壮性和开发效率，而 Vue 3 的 Composition API 则提供了更好的逻辑复用和代码组织能力。

代码格式化配置：

使用 Prettier 作为代码格式化工具，确保团队代码风格的统一。VS Code 用户可安装 Prettier 插件实现自动格式化。配置文件 .prettierrc 位于 web 目录下：

json
{
  "semi": false,
  "printWidth": 200,
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "arrowParens": "avoid",
  "trailingComma": "none",
  "bracketSpacing": true
}

配置项说明：

  • semi: 不使用分号结尾，保持代码简洁
  • printWidth: 单行最大长度 200 字符，适应现代宽屏显示器
  • tabWidth: 使用 2 个空格缩进，符合前端社区习惯
  • singleQuote: 使用单引号，与 Vue 生态保持一致
  • arrowParens: 箭头函数单参数时省略括号
  • trailingComma: 不使用尾随逗号，保持代码整洁

项目开发规范 ​

项目采用模块化架构设计，将复杂的业务功能拆分为独立的功能模块，每个模块具有完整的业务闭环和清晰的职责边界。这种设计模式提高了代码的可维护性、可测试性和团队协作效率。

模块化设计原则：

  • 单一职责：每个模块专注于特定的业务领域
  • 高内聚低耦合：模块内部功能紧密相关，模块间依赖最小化
  • 独立部署：支持模块的独立开发、测试和部署

标准目录结构：

以权限模块（modules/Permissions）为例，展示标准的模块目录组织：

├─permissions
│  ├─database          # 数据库相关文件
│  │  ├─migrations     # 数据库迁移文件
│  │  └─seeders        # 数据填充文件
│  ├─Exceptions        # 模块专用异常类
│  ├─Middlewares       # 模块中间件
│  ├─Providers         # 服务提供者
│  ├─routes            # 模块路由定义
│  ├─HTTP              # HTTP层业务逻辑
│  │  ├─Controllers    # 控制器类
│  │  └─Requests       # 表单验证请求类
│  └─Models            # 数据模型类
├─Installer.php        # 模块安装器

架构分层策略：

项目采用灵活的分层架构，根据模块复杂度选择合适的分层模式，避免过度设计。

轻量级分层（适用于简单模块）：

对于权限管理等相对简单的模块，采用 Controller → Model → Request 的轻量级分层：

  • Controller：处理 HTTP 请求和响应
  • Model：数据模型和基础业务逻辑
  • Request：表单验证和数据处理
  • Trait：公共逻辑的复用机制

这种模式的优势：

  • 调用链路短，便于调试和维护
  • 代码结构清晰，学习成本低
  • 避免过度抽象带来的复杂性

标准分层（适用于复杂模块）：

对于商城管理等复杂业务模块，引入 Controller → Service → Repository → Model 分层：

  • Service 层：封装复杂的业务逻辑和数据处理
  • Repository 层：数据访问抽象，支持多数据源
  • 业务聚合：处理跨模块的业务协调

分层选择原则：

  • 复杂度驱动：根据业务复杂度选择合适的分层深度
  • 团队协作：考虑团队规模和协作模式
  • 维护成本：平衡代码结构和维护难度
  • 性能考量：避免过深的调用链影响性能

通过这种灵活的分层策略，既保证了代码的可维护性，又避免了不必要的复杂性。