开发者必读

XYGo Admin 2025-02-20 300 次阅读

了解项目架构、开发规范和注意事项，避免踩坑

开发者必读

在开始开发之前，请务必阅读本文档，了解项目的核心架构和开发规范。

项目架构

XYGo Admin 采用经典的前后端分离架构：

复制代码

xygoadmin/
├── server/          # Go 后端（GoFrame）
│   ├── api/         # API 接口定义（请求/响应结构体）
│   ├── internal/
│   │   ├── cmd/         # 启动命令
│   │   ├── controller/  # 控制器（路由处理）
│   │   ├── logic/       # 业务逻辑（核心实现）
│   │   ├── service/     # 服务接口（自动生成）
│   │   ├── model/       # 数据模型
│   │   │   ├── entity/  # 数据库实体（自动生成）
│   │   │   ├── do/      # 数据操作对象（自动生成）
│   │   │   └── input/   # 输入/输出结构体
│   │   ├── dao/         # 数据访问层（自动生成）
│   │   └── middleware/  # 中间件
│   └── manifest/
│       └── config/      # 配置文件
└── web/             # Vue3 前端
    └── src/
        ├── api/         # API 请求封装
        ├── components/  # 公共组件
        ├── views/       # 页面视图
        ├── router/      # 路由配置
        ├── store/       # 状态管理
        └── utils/       # 工具函数

后端分层架构

请求处理遵循以下流程：

复制代码

HTTP Request
  → Middleware（鉴权、日志、响应包装）
    → Controller（参数校验、调用 Service）
      → Service（接口定义）
        → Logic（业务逻辑实现）
          → DAO（数据库操作）
            → Database

关键规则

Controller 层：只做参数接收和结果返回，不写业务逻辑
Logic 层：所有业务逻辑都在这里实现
Service 层：由 gf gen service 自动生成，不要手动修改
DAO 层：dao/internal/ 下的文件由 CLI 自动生成，不要修改；扩展方法写在 dao/ 外层
Entity/DO：由 gf gen dao 自动生成，不要手动修改

前端开发规范

组件命名

公共组件以 Art 前缀命名：ArtTable、ArtSearchBar、ArtSvgIcon
页面组件使用 PascalCase：UserList.vue、DocDialog.vue

图标使用

项目统一使用 Remix Icon 图标库，通过 ArtSvgIcon 组件引用：

vue 复制代码

<ArtSvgIcon icon="ri:home-line" class="text-xl" />

可在 Remix Icon 官网搜索图标。

网络请求

项目封装了三套请求实例，按场景使用：

实例	前缀	Token	用途
`adminRequest`	`/admin`	Bearer Token	后台管理接口
`memberRequest`	`/member`	Xy-User-Token	前台会员接口
`siteRequest`	`/site`	无	前台公共接口

状态管理

使用 Pinia 3 + 持久化插件，Store 文件放在 src/store/modules/ 下。

数据库规范

表名统一使用 xy_ 前缀
字段命名使用 snake_case
时间字段统一使用 UNIX 时间戳（bigint）
软删除字段：deleted_at（0 表示未删除）
必备字段：id、created_at、updated_at

Git 提交规范

项目使用 commitizen + cz-git，提交格式：

复制代码

feat: 新增用户管理模块
fix: 修复登录页验证码不显示
docs: 更新部署文档
style: 调整表格样式
refactor: 重构权限校验逻辑