返回文档中心

后端开发

XYGo Admin 2026-04-22 3 次阅读

路由注册、API/Controller/Logic开发规范

入口文件 module.go

module.go 是扩展的入口，在 init() 中完成路由注册和系统集成：

go 复制代码 
package shop

import (
    "xygo/internal/addon"
    "xygo/internal/middleware"
    "xygo/addons/shop/controller"

    // 空导入：触发 queues、crons 子包的 init() 注册
    _ "xygo/addons/shop/queues"
    _ "xygo/addons/shop/crons"

    "github.com/gogf/gf/v2/net/ghttp"
)

func init() {
    addon.Register(addon.Module{
        Name: "shop",
        Mount: func(s *ghttp.Server) {
            s.Group("/", func(group *ghttp.RouterGroup) {
                group.Middleware(
                    middleware.CORS,
                    middleware.ResponseHandler,
                    middleware.AdminAuth,
                )
                group.Bind(controller.NewV1())
            })
        },
    })
}

注意：queues/ 和 crons/ 是独立子包，必须通过空导入 _ "xygo/addons/shop/queues" 来触发它们的 init()。WebSocket 事件因为只是一行注册调用，通常直接写在 module.go 里即可。

系统启动时，addon.MountAll(s) 会自动调用所有已注册扩展的 Mount 函数挂载路由。

API 定义

在 api/ 目录下定义请求和响应结构体，使用 GoFrame 的规范路由标签：

go 复制代码 
package api

import "github.com/gogf/gf/v2/frame/g"

type ShopOrderListReq struct {
    g.Meta   `path:"/admin/shop/order/list" method:"get" tags:"商城" summary:"订单列表"`
    Page     int    `json:"page" d:"1"`
    PageSize int    `json:"pageSize" d:"20"`
    Status   *int   `json:"status"`
}
type ShopOrderListRes struct {
    g.Meta `mime:"application/json"`
}

type ShopOrderEditReq struct {
    g.Meta `path:"/admin/shop/order/edit" method:"post" tags:"商城" summary:"保存订单"`
    Id     uint64 `json:"id"`
}
type ShopOrderEditRes struct{}

type ShopOrderDeleteReq struct {
    g.Meta `path:"/admin/shop/order/delete" method:"post" tags:"商城" summary:"删除订单"`
    Id     uint64 `json:"id" v:"required"`
}
type ShopOrderDeleteRes struct{}

路由路径规范：/admin/{扩展名}/{实体名}/{操作}，如 /admin/shop/order/list。

Controller

go 复制代码 
package controller

import (
    "context"
    api "xygo/addons/shop/api"
    "xygo/addons/shop/logic"
)

type ControllerV1 struct{}

func NewV1() *ControllerV1 { return &ControllerV1{} }

func (c *ControllerV1) ShopOrderList(ctx context.Context, req *api.ShopOrderListReq) (res *api.ShopOrderListRes, err error) {
    return logic.OrderList(ctx, req)
}

func (c *ControllerV1) ShopOrderEdit(ctx context.Context, req *api.ShopOrderEditReq) (res *api.ShopOrderEditRes, err error) {
    return logic.OrderEdit(ctx, req)
}

func (c *ControllerV1) ShopOrderDelete(ctx context.Context, req *api.ShopOrderDeleteReq) (res *api.ShopOrderDeleteRes, err error) {
    return logic.OrderDelete(ctx, req)
}

Logic

go 复制代码 
package logic

import (
    "context"
    api "xygo/addons/shop/api"
)

func OrderList(ctx context.Context, req *api.ShopOrderListReq) (res *api.ShopOrderListRes, err error) {
    // 使用 g.DB() 或 dao 层查询数据库
    // 表名规范：xy_{扩展名}_xxx，如 xy_shop_order
    res = &api.ShopOrderListRes{}
    return
}

func OrderEdit(ctx context.Context, req *api.ShopOrderEditReq) (res *api.ShopOrderEditRes, err error) {
    return
}

func OrderDelete(ctx context.Context, req *api.ShopOrderDeleteReq) (res *api.ShopOrderDeleteRes, err error) {
    return
}