开箱即用的 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 目录。

步骤说明：

创建 user.go 文件，定义 Us`er 结构体及其配置。
通过 Annotations 配置表名、字符集等数据库属性。
通过 Fields 定义表字段，包括类型、约束（唯一、非空等）、注释。
通过 Mixin 复用通用字段（如 ID、时间戳），减少重复代码。
通过 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 目录。

步骤说明：

定义服务接口（service UserService），包含 CRUD 方法（如 CreateUser、ListUser）。
定义请求 / 响应消息（message），映射数据库字段和业务需求。
定义枚举（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）提升开发效率。

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

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

前置准备

开发环境

依赖工具

项目结构

一、设计数据库表结构

二、编写 ent 的 schema

关键代码解析：

生成 ent 代码：

三、编写 gRPC 的 proto 文件

步骤说明：

关键代码解析：

生成 Go 代码：

四、编写 REST 的 proto 文件

关键代码解析：

生成代码：

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

核心职责：

关键代码解析：

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

核心职责：

关键代码解析：

七、注册服务到 Server

gRPC 服务注册：

REST 服务注册：

八、测试新服务

1. 单元测试：

2. 接口测试：

gRPC 接口

HTTP 接口

总结

项目代码

微服务

热门文章

最新文章

相关电子书