目录结构与配置

XYGo Admin 2026-04-22 2 次阅读

扩展目录结构、addon.yaml完整配置说明

后端目录

复制代码

server/addons/{name}/
├── addon.yaml                  # 扩展元信息（必须）
├── module.go                   # 入口文件：路由注册（必须）
├── api/                        # API 定义（请求/响应结构体）
│   └── {name}_xxx.go
├── controller/                 # 控制器
│   └── xxx.go
├── logic/                      # 业务逻辑
│   └── xxx.go
├── model/                      # 数据模型
│   └── xxx.go
├── queues/                     # 消息队列消费者（按需创建）
│   └── xxx.go
├── crons/                      # 定时任务（按需创建）
│   └── xxx.go
├── install/                    # 安装 SQL
│   ├── pgsql.sql
│   └── mysql.sql
├── uninstall/                  # 卸载 SQL
│   ├── pgsql.sql
│   └── mysql.sql
└── upgrade/                    # 升级 SQL（幂等写法）
    ├── pgsql.sql
    └── mysql.sql

目录组织方式：queues/ 和 crons/ 是独立的 Go 子包，需要在 module.go 中空导入来触发 init() 注册。这与主包的 internal/queues/、internal/crons/ 模式完全一致。如果扩展功能简单（只有一两个消费者/任务），也可以不建子目录，直接在扩展根包下写 queues.go、crons.go。

前端目录

复制代码

web/src/addons/{name}/
├── api/                        # 前端 API 接口
│   └── xxx.ts
└── views/                      # 页面组件
    └── xxx/
        ├── index.vue
        └── modules/
            └── xxx-dialog.vue

addon.yaml 配置说明

addon.yaml 是扩展的元信息文件，安装器和打包器都会读取它。

yaml 复制代码

# 基础信息
name: shop                        # 扩展标识（英文小写，与目录名一致）
version: "1.0.0"                  # 当前版本号（语义化版本）
title: "商城管理"                  # 显示名称
description: "在线商城功能"        # 描述
author: "开发者A"                  # 作者

# 版本控制
min_version: "1.3.0"              # 要求的最低系统版本
min_upgrade_from: ""              # 最低可升级版本（留空不限制）

# 更新日志（升级时展示给用户）
changelog:
  - "新增订单管理"
  - "修复支付回调问题"

# 功能声明（仅用于说明，不影响逻辑）
features:
  routes: true
  websocket: false
  queue: false
  cron: false

# 菜单声明（安装时自动写入数据库）
menus:
  admin:                          # 后台管理菜单
    - title: "商城管理"
      name: "ShopManage"          # 必须以扩展名的 PascalCase 开头
      path: "shop"
      icon: "ri:shopping-cart-line"
      type: 1                     # 1=目录, 2=菜单, 3=按钮
      sort: 60
      children:
        - title: "订单管理"
          name: "ShopOrderList"
          path: "order"
          component: "@addons/shop/views/order"   # 前端组件路径
          type: 2
          sort: 1
          children:
            - title: "新增/编辑"
              name: "ShopOrderEdit"
              type: 3
              perms: "/admin/shop/order/edit"      # 权限标识
              sort: 1
            - title: "删除"
              name: "ShopOrderDelete"
              type: 3
              perms: "/admin/shop/order/delete"
              sort: 2
  tenant: []                      # 租户端菜单（结构相同）

菜单命名规范

所有菜单的 name 字段必须以扩展名的 PascalCase 为前缀
例如扩展名为 shop，菜单 name 必须以 Shop 开头：ShopManage、ShopOrderList 等
安装器会自动检测命名冲突，防止与系统菜单或其他扩展重名
卸载时按 remark='addon:{name}' 标记自动清除所有菜单

前端组件路径

菜单中的 component 使用 @addons/ 前缀，系统会自动映射到 web/src/addons/ 目录：

复制代码

@addons/shop/views/order → web/src/addons/shop/views/order/index.vue