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

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

前置准备

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

开发环境

依赖工具

# 安装相关的命令行工具
make cli
# 安装依赖的插件
make plugin

项目结构

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

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

一、设计数据库表结构

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

设计原则：

二、编写 GORM 数据模型

GORM 是 Go 语言主流的 ORM 库，通过结构体 + 标签定义数据库模型，无需手动编写 SQL 或生成代码。模型文件位于 backend/app/admin/service/internal/data/gorm/models 目录。

步骤说明：

1. 创建 user.go 文件，定义 User 结构体作为核心模型；
2. 通过 GORM 标签配置字段属性（主键、索引、非空、注释、字段类型等）；
3. 实现 TableName 方法指定数据库表名；

关键代码解析：

// backend/app/admin/service/internal/data/gorm/models/user.go
package models
import "gorm.io/gorm"
// User 用户信息表
type User struct {
   
    gorm.Model
    UserName string `gorm:"column:username;comment:'账号名'"`
    NickName string `gorm:"column:nickname;comment:'昵称'"`
    Password string `gorm:"column:password;comment:'登录密码'"`
}
func (u User) TableName() string {
   
    return "users"
}

表结构迁移：

GORM 无需手动生成代码，只需在把数据库模型注册进 MigrateModel列表 即可实现自动创建 / 更新表结构（仅新增字段，不会删除已有字段，保证数据安全）：

// backend/app/admin/service/internal/data/gorm/init.go
package gorm
import (
    "go-wind-admin/app/admin/service/internal/data/gorm/models"
    "github.com/tx7do/go-crud/gorm"
)
func init() {
   
    RegisterMigrates()
}
func RegisterMigrates() {
   
    gorm.RegisterMigrateModels(
        &models.User{
   },
    )
}

然后我们在backend/app/admin/service/internal/data/gorm_client.go里面引用执行init()方法即可实现自动创建更新表结构：

// backend/app/admin/service/internal/data/gorm_client.go
package data
import (
        _ "go-wind-admin/app/admin/service/internal/data/gorm"
)

三、编写 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 目录。

核心职责：

关键代码解析：

package data
import (
    "context"
    "errors"
    "go-wind-admin/api/gen/go/user/service/v1"
    "go-wind-admin/app/admin/service/internal/data/gorm/models"
    "gorm.io/gorm"
)
// UserRepo 用户数据访问仓库
type UserRepo struct {
   
    db  *gorm.DB          // GORM数据库连接
    log  *log.Helper      // 日志工具
}
// NewUserRepo 创建UserRepo实例
func NewUserRepo(logger log.Logger, db *gorm.DB) *UserRepo {
   
    repo := &UserRepo{
   
        log:                log.NewHelper(log.With(logger, "module", "user/repo/admin-service")),
        db:               db,
    }
    return repo
}
// CreateUser 创建用户
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
    }
    userModel := &models.User{
   
        Username:  *req.Data.Username,
        Password:  password,
        Nickname:  req.Data.GetNickname(),
    }
    // 执行GORM创建操作
    if err := r.db.WithContext(ctx).Create(userModel).Error; err != nil {
   
        r.log.Error("create user failed: %v", err)
        // 处理唯一键冲突（用户名重复）
        if errors.Is(err, gorm.ErrDuplicatedKey) {
   
            return userV1.ErrorAlreadyExists("username already exists")
        }
        return errors.New("failed to create user")
    }
    return nil
}
// ListUser 分页查询用户列表
func (r *UserRepo) ListUser(ctx context.Context, req *userV1.PagingRequest) (*userV1.ListUserResponse, error) {
   
    var (
        userModels []*model.User
        total      int64
        resp       = &userV1.ListUserResponse{
   }
    )
    // 分页参数处理
    page := req.GetPage()
    pageSize := req.GetPageSize()
    if page <= 0 {
   
        page = 1
    }
    if pageSize <= 0 {
   
        pageSize = 10
    }
    offset := (page - 1) * pageSize
    // 1. 查询总数（忽略软删除）
    if err := r.db.WithContext(ctx).Model(&model.User{
   }).Count(&total).Error; err != nil {
   
        r.log.Error("count user total failed: %v", err)
        return nil, errors.New("failed to count users")
    }
    resp.Total = total
    // 2. 分页查询列表
    if err := r.db.WithContext(ctx).Offset(int(offset)).Limit(int(pageSize)).Find(&userModels).Error; err != nil {
   
        r.log.Error("list users failed: %v", err)
        return nil, errors.New("failed to list users")
    }
    // 3. GORM模型转换为Proto消息
    resp.Items = make([]*userV1.User, 0, len(userModels))
    for _, u := range userModels {
   
        resp.Items = append(resp.Items, &userV1.User{
   
            Id:       uint32(u.ID),
            Username: &u.Username,
            Nickname: &u.Nickname,
        })
    }
    return resp, nil
}
// GetUser 查询单个用户（支持ID/用户名）
func (r *UserRepo) GetUser(ctx context.Context, req *userV1.GetUserRequest) (*userV1.User, error) {
   
    var userModel model.User
    // 根据条件查询（ID或用户名）
    switch {
   
    case req.Id != nil:
        if err := r.db.WithContext(ctx).First(&userModel, req.GetId()).Error; err != nil {
   
            if errors.Is(err, gorm.ErrRecordNotFound) {
   
                return nil, userV1.ErrorNotFound("user not found by id")
            }
            r.log.Error("get user by id failed: %v", err)
            return nil, errors.New("failed to get user")
        }
    case req.Username != nil:
        if err := r.db.WithContext(ctx).Where("username = ?", req.GetUsername()).First(&userModel).Error; err != nil {
   
            if errors.Is(err, gorm.ErrRecordNotFound) {
   
                return nil, userV1.ErrorNotFound("user not found by username")
            }
            r.log.Error("get user by username failed: %v", err)
            return nil, errors.New("failed to get user")
        }
    default:
        return nil, userV1.ErrorBadRequest("id or username is required")
    }
    // 转换为Proto消息
    return &userV1.User{
   
        Id:       uint32(userModel.ID),
        Username: &userModel.Username,
        Nickname: &userModel.Nickname,
        Email:    &userModel.Email,
        Phone:    &userModel.Phone,
        Status:   userV1.UserStatus(userModel.Status),
        RoleId:   uint32(userModel.RoleID),
        DeptId:   uint32(userModel.DeptID),
    }, nil
}
// UpdateUser 更新用户
func (r *UserRepo) UpdateUser(ctx context.Context, req *userV1.UpdateUserRequest) error {
   
    // 参数校验
    if req.Id == 0 || req.Data == nil {
   
        return userV1.ErrorBadRequest("id and data are required")
    }
        // 密码更新（可选）
    if req.Data.Password != nil && req.Data.GetPassword() != "" {
   
        cryptoPassword, err := crypto.HashPassword(req.Data.GetPassword())
        if err != nil {
   
            r.log.Error("hash password failed: %v", err)
            return errors.New("failed to hash password")
        }
        req.Data.Password = &cryptoPassword
    }
    // 构造更新数据
    updateData := &models.User{
   
        Username:  *req.Data.Username,
        Password:  password,
        Nickname:  req.Data.GetNickname(),
    }
    // 执行更新（仅更新非空字段）
    if err := r.db.WithContext(ctx).Model(&model.User{
   }).Where("id = ?", req.Id).Updates(updateData).Error; err != nil {
   
        r.log.Error("update user failed: %v", err)
        return errors.New("failed to update user")
    }
    return nil
}
// DeleteUser 删除用户（软删除）
func (r *UserRepo) DeleteUser(ctx context.Context, req *userV1.DeleteUserRequest) error {
   
    if req.Id == 0 {
   
        return userV1.ErrorBadRequest("id is required")
    }
    // GORM Delete方法默认软删除（更新DeletedAt字段）
    if err := r.db.WithContext(ctx).Delete(&model.User{
   }, req.Id).Error; err != nil {
   
        r.log.Error("delete user failed: %v", err)
        return errors.New("failed to delete user")
    }
    return nil
}

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

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

核心职责：

关键代码解析：

// backend/app/admin/service/internal/service/user_service.go
package service
import (
    "context"
    "errors"
    "go-wind-admin/api/gen/go/user/service/v1"
    "go-wind-admin/app/admin/service/internal/data"
    "google.golang.org/protobuf/types/known/emptypb"
)
// UserService 实现gRPC/REST服务接口
type UserService struct {
   
    userV1.UnimplementedUserServiceServer // 兼容gRPC
    userRepo *data.UserRepo
    log      *log.Helper
}
// NewUserService 创建UserService实例
func NewUserService(logger log.Logger, userRepo *data.UserRepo) *UserService {
   
    return &UserService{
   
        userRepo: userRepo,
        log:      log.NewHelper(log.With(logger, "module", "user/service/admin-service")),
    }
}
// CreateUser 创建用户（含权限校验）
func (s *UserService) CreateUser(ctx context.Context, req *userV1.CreateUserRequest) (*emptypb.Empty, error) {
   
    // 基础参数校验
    if req == nil || req.Data == nil {
   
        return nil, userV1.ErrorBadRequest("invalid request")
    }
    // 调用数据层创建用户
    if err := s.userRepo.CreateUser(ctx, req); err != nil {
   
        return nil, err
    }
    return &emptypb.Empty{
   }, nil
}
// ListUser 分页查询用户列表
func (s *UserService) ListUser(ctx context.Context, req *userV1.PagingRequest) (*userV1.ListUserResponse, error) {
   
    // 调用数据层查询
    resp, err := s.userRepo.ListUser(ctx, req)
    if err != nil {
   
        s.log.Error("list user failed: %v", err)
        return nil, err
    }
    return resp, nil
}
// GetUser 查询单个用户
func (s *UserService) GetUser(ctx context.Context, req *userV1.GetUserRequest) (*userV1.User, error) {
   
    // 调用数据层查询
    user, err := s.userRepo.GetUser(ctx, req)
    if err != nil {
   
        s.log.Error("get user failed: %v", err)
        return nil, err
    }
    return user, nil
}
// UpdateUser 更新用户
func (s *UserService) UpdateUser(ctx context.Context, req *userV1.UpdateUserRequest) (*emptypb.Empty, error) {
   
    // 1. 校验超级管理员不可被修改
    if req.Id == 1 {
    // 假设1是超级管理员ID
        return nil, userV1.ErrorPermissionDenied("cannot update super admin")
    }
    // 2. 调用数据层更新
    if err := s.userRepo.UpdateUser(ctx, req); err != nil {
   
        s.log.Error("update user failed: %v", err)
        return nil, err
    }
    return &emptypb.Empty{
   }, nil
}
// DeleteUser 删除用户
func (s *UserService) DeleteUser(ctx context.Context, req *userV1.DeleteUserRequest) (*emptypb.Empty, error) {
   
    // 1. 校验超级管理员不可被删除
    if req.Id == 1 {
   
        return nil, userV1.ErrorPermissionDenied("cannot delete super admin")
    }
    // 2. 调用数据层删除
    if err := s.userRepo.DeleteUser(ctx, req); err != nil {
   
        s.log.Error("delete user failed: %v", err)
        return nil, err
    }
    return &emptypb.Empty{
   }, nil
}

七、注册服务到 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 user.service.v1.UserService
# 调用创建用户接口
grpcurl -plaintext -d '{
  "data": {
    "username": "test_admin",
    "nickname": "测试管理员",
    "password": "12345678"
  },
  "operator_id": 1
}' localhost:9000 user.service.v1.UserService/CreateUser
# 调用列表查询接口
grpcurl -plaintext -d '{"page": 1, "page_size": 10}' localhost:9000 user.service.v1.UserService/ListUser

HTTP 接口

使用 curl 或 Postman 调用：

# 创建用户
curl -X POST http://localhost:8080/admin/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "username": "test_admin",
      "nickname": "测试管理员",
      "password": "12345678"
    },
    "operator_id": 1
  }'
# 查询用户列表
curl -X GET "http://localhost:8080/admin/v1/users?page=1&page_size=10"
# 查询单个用户
curl -X GET http://localhost:8080/admin/v1/users/1
# 更新用户
curl -X PUT http://localhost:8080/admin/v1/users/1 \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "nickname": "更新后的昵称"
    },
    "operator_id": 1
  }'
# 删除用户
curl -X DELETE http://localhost:8080/admin/v1/users/2

总结

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

相较于 Ent，GORM 更轻量化、学习成本更低，无需代码生成步骤，适合快速开发；同时 GORM 提供丰富的查询语法、软删除、自动迁移等特性，完全满足企业级中后台系统的需求。遵循此流程，你可快速在 GoWind Admin 中扩展任意新服务，充分利用 GORM 的便捷性提升开发效率。

项目代码