AI 助理
备案控制台
开发者社区 云原生 微服务 文章 正文

开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：基于 Ent 从零实现新服务

2025-12-12 32
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： GoWind Admin（风行）是基于 Ent 的企业级中后台框架，支持 gRPC 与 REST 双协议。本文详解如何从零构建服务：通过 Ent 设计表结构并生成 ORM 代码，用 Protobuf 定义接口契约，分层实现 data 与 service 逻辑，最后注册至服务器。提供完整单元测试与接口验证方案，开箱即用，助力高效开发。

开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：基于 Ent 从零实现新服务

本文将指导开发者在 GoWind Admin 企业级前后端一体中后台框架中，从零开始构建一个完整的 gRPC 服务。我们所指的 “服务” 即 gRPC 中的 service，通常包含特定数据集的 CRUD（增删改查）操作，遵循框架规范实现高可维护性与可扩展性。

前置准备

在开始前，请确保已完成以下环境准备：

开发环境

  • Go 1.19+（推荐 1.21+，支持最新语言特性）
  • Git（版本控制）
  • Protobuf 编译器（protoc，用于编译 proto 文件）

依赖工具

# 安装相关的命令行工具
make cli

# 安装依赖的插件
make plugin

项目结构

克隆 GoWind Admin 项目后，核心目录结构如下（聚焦服务开发相关目录）：

go-wind-admin/
├── backend/
│   ├── api/gen/go/        # proto 编译生成的 Go 代码（自动生成，无需手动修改）
│   ├── api/proto/         # 存放 proto 接口定义文件
│   ├── app/admin/service/ # 业务服务核心实现
│   │   ├── internal/
│   │   │   ├── data/      # 数据访问层（与数据库交互，基于 ent）
│   │   │   │   └── ent/   # ent ORM 自动生成的数据库操作代码
│   │   │   └── service/   # 业务逻辑层（实现 gRPC 接口）
│   │   └── server/        # 服务注册（将服务绑定到 gRPC/HTTP 服务器）

一、设计数据库表结构

数据库表结构是服务的基础，需根据业务需求设计核心字段。以 “用户表” 为例，需包含：

  • 通用字段：ID（主键）、创建时间、更新时间、创建者 ID、更新者 ID（用于审计）
  • 业务字段：用户名（唯一）、密码、昵称、邮箱、手机号等
  • 关联字段：角色 ID、部门 ID 等（用于关联其他表）
  • 状态字段：用户状态（启用 / 禁用）、性别等枚举字段

设计原则：

  • 核心字段非空（如用户名），非核心字段可空（如地址）
  • 频繁查询的字段添加索引（如用户名）
  • 敏感字段（如密码）需加密存储

二、编写 ent 的 schema

Ent 是 Go 语言的 ORM 库，通过 schema 定义数据库实体。schema 文件位于 backend/app/admin/service/internal/data/ent/schema 目录。

步骤说明：

  1. 创建 user.go 文件，定义 Us`er 结构体及其配置。
  2. 通过 Annotations 配置表名、字符集等数据库属性。
  3. 通过 Fields 定义表字段，包括类型、约束（唯一、非空等）、注释。
  4. 通过 Mixin 复用通用字段（如 ID、时间戳），减少重复代码。
  5. 通过 Indexes 定义索引，提升查询性能。

关键代码解析：

// Annotations 配置表基本信息
func (User) Annotations() []schema.Annotation {
   
    return []schema.Annotation{
   
        entsql.Annotation{
   
            Table:     "sys_users", // 数据库表名
            Charset:   "utf8mb4",   // 字符集
            Collation: "utf8mb4_bin", // 排序规则
        },
        schema.Comment("用户表"), // 表注释
    }
}

// Fields 定义表字段
func (User) Fields() []ent.Field {
   
    return []ent.Field{
   
        field.String("username").
            Comment("用户名").
            Unique().       // 唯一索引
            NotEmpty().     // 非空
            Immutable(),    // 创建后不可修改

        field.String("password").
            Comment("登录密码").
            MaxLen(255).    // 最大长度
            Sensitive(),    // 敏感字段（日志中隐藏）

        // 其他字段...
    }
}

// Mixin 复用通用配置
func (User) Mixin() []ent.Mixin {
   
    return []ent.Mixin{
   
        mixin.AutoIncrementId{
   }, // 自增 ID
        mixin.TimeAt{
   },          // 创建时间、更新时间
        mixin.OperatorID{
   },      // 创建者、更新者 ID
    }
}

生成 ent 代码：

编写完 schema 后，执行以下命令生成实体代码：

cd backend/app/admin/service/
make ent

三、编写 gRPC 的 proto 文件

Protobuf（proto）用于定义 gRPC 服务接口和数据结构，是服务对外暴露的 “契约”。proto 文件通常位于 backend/api/proto/user/service/v1 目录。

步骤说明：

  1. 定义服务接口（service UserService），包含 CRUD 方法（如 CreateUser、ListUser）。
  2. 定义请求 / 响应消息（message），映射数据库字段和业务需求。
  3. 定义枚举（enum），如用户状态、性别等固定值类型。

关键代码解析：

// backend/api/proto/user/service/v1/user.proto

// 定义服务接口
service UserService {
  rpc ListUser (pagination.PagingRequest) returns (ListUserResponse); // 列表查询
  rpc GetUser (GetUserRequest) returns (User);                        // 详情查询
  rpc CreateUser (CreateUserRequest) returns (google.protobuf.Empty); // 创建
  rpc UpdateUser (UpdateUserRequest) returns (google.protobuf.Empty); // 更新
  rpc DeleteUser (DeleteUserRequest) returns (google.protobuf.Empty); // 删除
}

// 枚举定义（用户状态）
enum UserStatus {
  OFF = 0; // 禁用
  ON = 1;  // 启用
}

// 数据模型（与数据库表对应）
message User {
  optional uint32 id = 1 [json_name = "id"]; // 用户ID
  optional string username = 2;              // 用户名
  optional UserStatus status = 3;            // 状态
  // 其他字段...
}

生成 Go 代码：

执行以下命令将 proto 转换为 Go 代码（生成的代码位于 backend/api/gen/go 目录）：

make api

四、编写 REST 的 proto 文件

Protobuf（proto）用于定义 REST 服务接口和数据结构，是服务对外暴露的 “契约”。proto 文件通常位于 backend/api/proto/admin/service/v1 目录。

关键代码解析：

// backend/api/proto/admin/service/v1/i_user.proto

import "user/service/v1/user.proto";

// 用户管理服务
service UserService {
  // 获取用户列表
  rpc List (pagination.PagingRequest) returns (user.service.v1.ListUserResponse) {
    option (redact.v3.internal_method) = true;
    option (google.api.http) = {
      get: "/admin/v1/users"
    };
  }

  // 获取用户数据
  rpc Get (user.service.v1.GetUserRequest) returns (user.service.v1.User) {
    option (redact.v3.internal_method) = true;
    option (google.api.http) = {
      get: "/admin/v1/users/{id}"
      additional_bindings {
        get: "/admin/v1/users/username/{user_name}"
      }
    };
  }

  // 创建用户
  rpc Create (user.service.v1.CreateUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/admin/v1/users"
      body: "*"
    };
  }

  // 更新用户
  rpc Update (user.service.v1.UpdateUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      put: "/admin/v1/users/{id}"
      body: "*"
    };
  }

  // 删除用户
  rpc Delete (user.service.v1.DeleteUserRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/admin/v1/users/{id}"
    };
  }
}

// 枚举定义（用户状态）
enum UserStatus {
  OFF = 0; // 禁用
  ON = 1;  // 启用
}

// 数据模型（与数据库表对应）
message User {
  optional uint32 id = 1 [json_name = "id"]; // 用户ID
  optional string username = 2;              // 用户名
  optional UserStatus status = 3;            // 状态
  // 其他字段...
}

生成代码：

执行以下命令将 proto 转换为 Go 代码（生成的代码位于 backend/api/gen/go 目录）：

# 生成go代码
make api

执行以下命令将 proto 转换为 OpenAPI文档（生成的文档位于backend/app/admin/service/cmd/server/assets/目录）：

# 生成OpenAPI文档
make openapi

执行以下命令将 proto 转换为 TypeScript代码（生成的代码位于frontend/apps/admin/src/generated/api目录）：

# 生成TypeScript代码
make ts

五、编写 data 包（数据访问层）

data 包负责与数据库交互，实现 CRUD 操作，是业务逻辑与数据库之间的桥梁。代码位于 backend/app/admin/service/internal/data 目录。

核心职责：

  • 封装 ent 的数据库操作（查询、插入、更新、删除）。
  • 实现 ent 实体与 proto 消息的转换（如 convertEntToProto）。
  • 处理数据访问过程中的错误（如记录日志、返回业务错误）。

关键代码解析：

package data

type UserRepo struct {
   
    data *Data
    log  *log.Helper

    mapper             *mapper.CopierMapper[userV1.User, ent.User]
}

func NewUserRepo(logger log.Logger, data *Data) *UserRepo {
   
    repo := &UserRepo{
   
        log:                log.NewHelper(log.With(logger, "module", "user/repo/admin-service")),
        data:               data,
        mapper:             mapper.NewCopierMapper[userV1.User, ent.User](),
    }

    return repo
}

// 创建用户
func (r *UserRepo) CreateUser(ctx context.Context, req *userV1.CreateUserRequest) error {
   
    if req == nil || req.Data == nil {
   
        return nil, userV1.ErrorBadRequest("invalid parameter")
    }

    if req.Data.Password != nil && req.Data.GetPassword() != "" {
   
        cryptoPassword, err := crypto.HashPassword(req.Data.GetPassword())
        if err != nil {
   
            return nil, err
        }
        req.Data.Password = &cryptoPassword
    }

    // 调用 ent 插入数据
    return r.data.db.Client().User.Create().
        SetUsername(req.Data.Username).
        SetPassword(req.Data.GetPassword()).
        // 设置其他字段...
        Exec(ctx)
}

六、编写 service 包（业务逻辑层）

service 包实现核心业务逻辑，调用 data 包进行数据操作，并处理权限校验、参数校验等业务规则。代码位于 backend/app/admin/service/internal/service 目录。

核心职责：

  • 校验请求参数合法性（如非空检查）。
  • 实现业务规则（如 “禁止删除超级管理员”）。
  • 调用 data 包完成数据操作，并返回结果。

关键代码解析：

// 创建用户（包含权限校验）
func (s *UserService) CreateUser(ctx context.Context, req *userV1.CreateUserRequest) (*emptypb.Empty, error) {
   
    // 参数校验
    if req.Data == nil || req.Data.Username == nil {
   
        return nil, errors.New("用户名不能为空")
    }

    // 权限校验：只有管理员能创建用户
    operator, err := s.userRepo.GetUser(ctx, req.OperatorId)
    if err != nil || operator.Authority != userV1.UserAuthority_SYS_ADMIN {
   
        return nil, errors.New("权限不足")
    }

    // 调用 data 包创建用户
    return &emptypb.Empty{
   }, s.userRepo.CreateUser(ctx, req)
}

七、注册服务到 Server

最后需将服务注册到 gRPC 或 REST 服务器，使客户端能访问服务。注册代码位于 backend/app/admin/service/server 目录。

gRPC 服务注册：

import (
    "github.com/go-kratos/kratos/v2/transport/grpc"
)

// 注册 gRPC 服务
func NewGRPCServer(cfg *conf.Bootstrap, userSvc *service.UserService) *grpc.Server {
   
    srv := grpc.NewServer()

    // 将 UserService 注册到 gRPC 服务器
    userV1.RegisterUserServiceServer(srv, userSvc)

    return srv
}

REST 服务注册：

import (
    "github.com/go-kratos/kratos/v2/transport/http"
)

// 注册 REST 服务
func NewRESTServer(cfg *conf.Bootstrap, userSvc *service.UserService) *http.Server {
   
    if cfg == nil || cfg.Server == nil || cfg.Server.Rest == nil {
   
        return nil
    }

    srv := rpc.CreateRestServer(cfg)

    // 将 UserService 注册到 REST 服务器
    adminV1.RegisterUserServiceHTTPServer(srv, userSvc)

    return srv
}

八、测试新服务

服务开发完成后，需验证功能正确性：

1. 单元测试：

测试 data 包和 service 包的核心方法（使用 Go 内置测试框架）：

// backend/app/admin/service/internal/service/user_service_test.go
package service_test

import (
    "context"
    "testing"

    "github.com/stretchr/testify/assert"
    userV1 "go-wind-admin/api/gen/go/admin/service/v1"
    "go-wind-admin/app/admin/service/internal/service"
    "go-wind-admin/mocks"
)

func TestCreateUser(t *testing.T) {
   
    // 初始化 mock 依赖
    mockUserRepo := mocks.NewUserRepo(t)
    svc := service.NewUserService(mockUserRepo, nil)

    // 测试用例：用户名空
    req := &userV1.CreateUserRequest{
   Password: "12345678"}
    _, err := svc.CreateUser(context.Background(), req)
    assert.ErrorContains(t, err, "用户名不能为空")

    // 其他测试用例...
}

2. 接口测试：

gRPC 接口

使用 grpcurl 调用：

# 列出服务接口
grpcurl -plaintext localhost:9000 list admin.service.v1.UserService

# 调用创建用户接口
grpcurl -plaintext -d '{"username":"test","password":"12345678"}' \
  localhost:9000 admin.service.v1.UserService/CreateUser

HTTP 接口

使用 curl 或 Postman 调用：

# 创建用户
curl -X POST http://localhost:8080/admin/v1/users \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"12345678"}'

总结

通过以上步骤，我们完成了一个新服务从数据库设计到接口暴露的全流程实现。GoWind Admin 框架的分层架构（schema → data → service → server）确保了代码的低耦合与高可维护性：

  • schema 层：通过 ent 定义数据结构，自动生成数据库操作代码。
  • data 层：封装数据库交互，隔离业务逻辑与数据访问。
  • service 层：聚焦业务规则，与数据层解耦。
  • server 层：统一注册服务，简化部署与扩展。

遵循此流程，开发者可快速在框架中扩展新服务，充分利用框架提供的工具链（ent、Protobuf、gRPC）提升开发效率。

项目代码

文章标签：
数据库
Go
网络架构
API
数据安全/隐私保护
杨粼波
目录
相关文章
杨粼波
|
1天前
|
Go API 数据库
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：基于 GORM 从零实现新服务
GoWind Admin 是基于 GORM 的企业级中后台框架，支持 gRPC 与 REST 双协议。本文详解如何从零构建服务：设计表结构、编写 GORM 模型、定义 Proto 接口、实现数据访问与业务逻辑，并注册服务。分层架构清晰，开箱即用，助力高效开发。
杨粼波
34 4
阿里云开发者
|
16天前
|
存储 SQL 分布式计算
手把手教你搞定大数据上云：数据迁移的全流程解析
本文深入探讨了企业数据迁移的核心价值与复杂挑战，重点分析了离线大数据平台在物理传输、系统耦合与数据校验三方面的难题。文章系统阐述了存储格式、表格式、计算引擎等关键技术原理，并结合LHM等工具介绍了自动化迁移的实践演进，展望了未来智能化、闭环化的数据流动方向。
阿里云开发者
338 11
手把手教你搞定大数据上云：数据迁移的全流程解析
杨粼波
|
前端开发 Go API
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：数据脱敏和隐私保护
GoWind Admin基于Protobuf生态，集成protoc-gen-redact插件，实现开箱即用的数据脱敏与隐私保护。通过注解定义规则，自动生成脱敏代码，支持多语言、灵活配置，零侵入业务逻辑，适用于微服务、日志、前端等场景，保障数据安全合规。
杨粼波
82 0
杨粼波
|
8天前
|
前端开发 JavaScript Go
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：为什么选 Golang+Vue3 这套组合？
go-wind-admin 采用 Golang + Vue3 技术栈，融合高性能后端与高效前端生态。后端基于 go-kratos、ent/gorm 灵活适配复杂业务，前端结合 Vue3、TypeScript 与 Vben Admin，提升开发效率与可维护性，兼顾性能、扩展性与企业级需求，是中后台系统的理想选择。（239字）
杨粼波
93 6
杨粼波
|
前端开发 安全 API
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：自动化解放双手，初学者快速搭建系统并自动生成前端接口
GoWind Admin 是基于 Go-Kratos 与 Vue3 的企业级中后台框架，开箱即用，集成用户、权限、租户等核心模块。搭配 protoc-gen-typescript-http，可从 Protobuf 自动生成类型安全的前端接口，大幅降低联调成本，提升开发效率，助力初学者快速搭建系统，实现前后端高效协作。
杨粼波
145 0
阿里云开发者
|
8天前
|
存储 人工智能 自然语言处理
LlamaIndex 深度实战：用《长安的荔枝》学会构建智能问答系统
本文深入浅出地讲解了RAG（检索增强生成）原理与LlamaIndex实战，通过《长安的荔枝》案例，从AI如何“读书”讲起，详解三大关键参数（chunk_size、top_k、overlap）对问答效果的影响，并结合真实实验展示不同配置下的回答质量差异。内容兼顾新手引导与进阶优化，帮助读者快速构建高效的文档问答系统。
阿里云开发者
196 7
LlamaIndex 深度实战：用《长安的荔枝》学会构建智能问答系统
阿里云开发者
|
8天前
|
人工智能 安全 Java
SpecKit 在成熟 Java 项目中的 AI 编码实践
本文探索AI Code与SpecKit在Java应用中的实践，结合规格驱动开发（SDD）与测试驱动开发（TDD），通过定义原则、需求规格化、技术方案设计等步骤，实现风格统一、可追溯的AI辅助编码。分享选型考量、执行流程及问题优化，总结经验并沉淀为应用级知识资产，提升研发效率与代码规范性。（239字）
阿里云开发者
202 5
SpecKit 在成熟 Java 项目中的 AI 编码实践
阿里云开发者
|
16天前
|
存储 数据采集 监控
分钟级定位 IO 瓶颈：多租户云环境下的智能诊断
阿里云推出IO一键诊断功能，智能识别IO延迟高、流量异常等问题，通过动态阈值与多指标关联分析，实现秒级异常发现与根因定位，提升云环境存储性能问题解决效率。
阿里云开发者
150 10
分钟级定位 IO 瓶颈：多租户云环境下的智能诊断
阿里云云原生
|
5天前
|
Kubernetes Cloud Native Nacos
MCP 网关实战：基于 Higress + Nacos 的零代码工具扩展方案
本文会围绕如何基于 Higress 和 Nacos 的 docker 镜像在 K8s 集群上进行分角色部署。
阿里云云原生
96 12
杨粼波
|
6月前
|
JSON API Go
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：集成 Swagger UI 打造交互式 API 文档
GoWind Admin（风行）是基于 Kratos 的企业级中后台框架，集成 Swagger UI 实现交互式 API 文档。通过 Protobuf 自动生成 OpenAPI v3 规范文档，利用 `//go:embed` 嵌入服务，一键部署可视化调试界面，提升前后端协作效率，开箱即用。
杨粼波
321 1
开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：集成 Swagger UI 打造交互式 API 文档
云原生

微服务

热门文章

最新文章

  • 1
    微服务架构的理论基础 - 康威定律
  • 2
    微服务选择Spring Cloud还是Dubbo？
  • 3
    ASP.NET Core微服务之基于Consul实现服务治理（1）
  • 4
    微服务架构下分布式事务解决方案 —— 阿里GTS
  • 5
    微服务架构
  • 6
    五分钟内免费体验 EDAS ，完美解决微服务痛点
  • 7
    编码实现Spring Cloud微服务负载均衡调用（eureka、ribbon）
  • 8
    Spring Cloud构建微服务架构-创建“服务提供方”
  • 9
    阿里巴巴微服务开源项目盘点（持续更新）
  • 10
    微服务开源生态报告 No.7
  • 1
    架构级拆解：AI数字人与数字员工的核心差异，玄晶引擎云原生实践启示
    56
  • 2
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：基于 Ent 从零实现新服务
    32
  • 3
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：基于 GORM 从零实现新服务
    34
  • 4
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：如何进行Docker部署后端
    31
  • 5
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：支持ClickHouse
    29
  • 6
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：为什么选 Golang+Vue3 这套组合？
    93
  • 7
    初学者友好：Go-Kratos 集成 go-crud，GORM ORM CRUD 无需重复编码，轻松上手
    83
  • 8
    初学者友好：Go-Kratos 集成 go-crud，Ent ORM CRUD 无需重复编码，轻松上手
    73
  • 9
    开箱即用的 GoWind Admin｜风行，企业级前后端一体中后台框架：MongoDB集成指南（从部署到实战全攻略）
    63
  • 10
    阿里云微服务引擎 MSE 及 API 网关 2025 年 11 月产品动态
    101

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    「直播预告」Streaming Lakehouse Meetup EP.2｜Paimon × StarRocks 共话实时湖仓