用户管理系统 API 文档

概述

本文档描述了用户管理系统的 gRPC API 接口，包含用户认证、权限管理、部门管理、用户管理和角色管理等功能模块。

包信息

• 包名: grpc
• Go 包: user
• 语法版本: proto3

导入依赖

import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/empty.proto";

通用消息类型

UserInfo

用户信息结构体

字段	类型	描述
user_id	int64	用户ID
user_name	string	用户名
nickname	string	昵称
mobile	string	手机号
email	string	邮箱
department_id	int64	部门ID
department_name	string	部门名称
organization_code	string	组织机构代码
organization_name	string	组织机构名称

Permission

权限信息结构体

字段	类型	描述
permission_name	string	权限名称
permission_code	string	权限代码
permission_id	int64	权限ID
parent_id	int64	父权限ID
group_name	string	权限组名称
group_name_desc	string	权限组描述

Department

部门信息结构体

字段	类型	描述
department_id	int64	部门ID
department_name	string	部门名称
pid	int64	父部门ID

User

用户详细信息结构体

字段	类型	描述
user_id	int64	用户ID
user_name	string	用户名
nickname	string	昵称
mobile	string	手机号
email	string	邮箱
department_id	string	部门ID
department_name	string	部门名称
create_time	string	创建时间
role_id	int64	角色ID
role_name	string	角色名称

Role

角色信息结构体

字段	类型	描述
role_id	int64	角色ID
role_name	string	角色名称

服务接口

1. 用户认证服务 (AuthService)

1.1 用户注册

方法: RegisterUser

请求参数:

message RegisterRequest {
  string user_name = 1;           // 用户名称
  string nickname = 2;            // 昵称
  string mobile = 3;              // 手机号
  string email = 4;               // 邮箱
  string password = 5;            // 密码
  string organization_code = 6;   // 组织机构代码
  string organization_name = 7;   // 组织机构名称
}

响应参数:

message RegisterResponse {
  UserInfo UserInfo = 2;          // 用户信息
}

1.2 用户登录

方法: Login

请求参数:

message LoginRequest {
  string user_name = 1;           // 用户名
  string password = 2;            // 密码
}

响应参数:

message LoginResponse {
  string access_token = 2;        // 访问令牌
  int64 expires_at = 3;          // 过期时间
}

1.3 获取用户信息

方法: UserInfo

请求参数:

message UserInfoRequest {
  string access_token = 2;        // 访问令牌
}

响应参数:

message UserInfoResponse {
  UserInfo UserInfo = 2;          // 用户信息
  repeated Permission Permission = 3;  // 权限列表
}

1.4 更新用户信息

方法: UpdateUserInfo

请求参数:

message UpdateUserInfoRequest {
  string access_token = 1;        // 访问令牌
  string nickname = 2;            // 昵称
  string mobile = 3;              // 手机号
  string email = 4;               // 邮箱
}

响应参数:

message UpdateUserInfoResponse {
  // 空响应
}

1.5 修改密码

方法: UpdatePassword

请求参数:

message UpdatePasswordRequest {
  string access_token = 1;        // 访问令牌
  string old_password = 2;        // 旧密码
  string new_password = 3;        // 新密码
}

响应参数:

message UpdatePasswordResponse {
  // 空响应
}

2. 权限管理服务 (PermissionService)

2.1 获取权限列表

方法: GetPermissionList

请求参数:

message GetPermissionListRequest {
  string access_token = 1;        // 访问令牌
  string group_name = 2;          // 权限组名称
}

响应参数:

message GetPermissionListResponse {
  repeated Permission Permission = 3;  // 权限列表
}

2.2 添加权限

方法: AddPermission

请求参数:

message AddPermissionRequest {
  string access_token = 1;        // 访问令牌
  int64 pid = 2;                  // 父权限ID
  string name = 3;                // 权限名称
  string sign = 4;                // 权限标识符
  string group_name = 5;          // 组名称
  string group_name_desc = 6;     // 组名称描述
}

响应参数:

message AddPermissionResponse {
  // 空响应
}

2.3 更新权限

方法: UpdatePermission

请求参数:

message UpdatePermissionRequest {
  string access_token = 1;        // 访问令牌
  int64 permission_id = 2;        // 权限ID
  int64 pid = 3;                  // 父权限ID
  string name = 4;                // 权限名称
  string sign = 5;                // 权限标识符
  string group_name = 6;          // 组名称
  string group_name_desc = 7;     // 组名称描述
}

响应参数:

message UpdatePermissionResponse {
  // 空响应
}

2.4 删除权限

方法: DeletePermission

请求参数:

message DeletePermissionRequest {
  string access_token = 1;        // 访问令牌
  int64 permission_id = 2;        // 权限ID
}

响应参数:

message DeletePermissionResponse {
  // 空响应
}

3. 部门管理服务 (DepartmentService)

3.1 获取部门列表

方法: GetDepartmentList

请求参数:

message GetDepartmentListRequest {
  string access_token = 1;        // 访问令牌
}

响应参数:

message GetDepartmentListResponse {
  repeated Department Department = 3;  // 部门列表
}

3.2 添加部门

方法: AddDepartment

请求参数:

message AddDepartmentRequest {
  string access_token = 1;        // 访问令牌
  string department_name = 2;     // 部门名称
  int64 pid = 3;                  // 父部门ID
}

响应参数:

message AddDepartmentResponse {
  // 空响应
}

3.3 更新部门

方法: UpdateDepartment

请求参数:

message UpdateDepartmentRequest {
  string access_token = 1;        // 访问令牌
  int64 department_id = 2;        // 部门ID
  string department_name = 3;     // 部门名称
}

响应参数:

message UpdateDepartmentResponse {
  // 空响应
}

3.4 删除部门

方法: DeleteDepartment

请求参数:

message DeleteDepartmentRequest {
  string access_token = 1;        // 访问令牌
  int64 department_id = 2;        // 部门ID
}

响应参数:

message DeleteDepartmentResponse {
  // 空响应
}

4. 用户管理服务 (UserService)

4.1 获取用户列表

方法: GetUserList

请求参数:

message GetUserListRequest {
  string access_token = 1;        // 访问令牌
  string nickname = 2;            // 昵称（可选）
  string mobile = 3;              // 手机号（可选）
  string email = 4;               // 邮箱（可选）
  string department_id = 5;       // 部门ID（可选）
  string start_create_time = 6;   // 开始创建时间（可选）
  string end_create_time = 7;     // 结束创建时间（可选）
}

响应参数:

message GetUserListResponse {
  repeated User User = 3;         // 用户列表
}

4.2 添加用户

方法: AddUser

请求参数:

message AddUserRequest {
  string access_token = 1;        // 访问令牌
  string user_name = 2;           // 用户名
  string nickname = 3;            // 昵称
  string mobile = 4;              // 手机号
  string email = 5;               // 邮箱
  string department_id = 6;       // 部门ID
  string password = 7;            // 密码
  int64 role_id = 8;              // 角色ID
}

响应参数:

message AddUserResponse {
  // 空响应
}

4.3 更新用户

方法: UpdateUser

请求参数:

message UpdateUserRequest {
  string access_token = 1;        // 访问令牌
  int64 user_id = 2;              // 用户ID
  string nickname = 3;            // 昵称
  string mobile = 4;              // 手机号
  string email = 5;               // 邮箱
  string department_id = 6;       // 部门ID
  int64 role_id = 7;              // 角色ID
}

响应参数:

message UpdateUserResponse {
  // 空响应
}

4.4 删除用户

方法: DeleteUser

请求参数:

message DeleteUserRequest {
  string access_token = 1;        // 访问令牌
  int64 user_id = 2;              // 用户ID
}

响应参数:

message DeleteUserResponse {
  // 空响应
}

4.5 获取用户详情

方法: GetUserInfo

请求参数:

message GetUserInfoRequest {
  string access_token = 1;        // 访问令牌
  int64 user_id = 2;              // 用户ID
}

响应参数:

message GetUserInfoResponse {
  User User = 3;                  // 用户信息
}

4.6 重置密码

方法: ResetPassword

请求参数:

message ResetPasswordRequest {
  string access_token = 1;        // 访问令牌
  int64 user_id = 2;              // 用户ID
  string password = 3;            // 新密码
}

响应参数:

message ResetPasswordResponse {
  // 空响应
}

5. 角色管理服务 (RoleService)

5.1 获取角色列表

方法: GetRoleList

请求参数:

message GetRoleListRequest {
  string access_token = 1;        // 访问令牌
  string role_name = 2;           // 角色名称（可选）
}

响应参数:

message GetRoleListResponse {
  repeated Role Role = 3;         // 角色列表
}

5.2 添加角色

方法: AddRole

请求参数:

message AddRoleRequest {
  string access_token = 1;        // 访问令牌
  string role_name = 2;           // 角色名称
}

响应参数:

message AddRoleResponse {
  // 空响应
}

5.3 更新角色

方法: UpdateRole

请求参数:

message UpdateRoleRequest {
  string access_token = 1;        // 访问令牌
  int64 role_id = 2;              // 角色ID
  string role_name = 3;           // 角色名称
}

响应参数:

message UpdateRoleResponse {
  // 空响应
}

5.4 删除角色

方法: DeleteRole

请求参数:

message DeleteRoleRequest {
  string access_token = 1;        // 访问令牌
  int64 role_id = 2;              // 角色ID
}

响应参数:

message DeleteRoleResponse {
  // 空响应
}

5.5 获取角色权限

方法: GetRolePermission

请求参数:

message GetRolePermissionRequest {
  string access_token = 1;        // 访问令牌
  int64 role_id = 2;              // 角色ID
  string group_name = 3;          // 权限组名称（可选）
  string permission_name = 4;     // 权限名称（可选）
}

响应参数:

message GetRolePermissionResponse {
  repeated Permission Permission = 3;  // 权限列表
}

5.6 添加角色权限

方法: AddRolePermission

请求参数:

message AddRolePermissionRequest {
  string access_token = 1;        // 访问令牌
  int64 role_id = 2;              // 角色ID
  repeated int64 permission_ids = 3;  // 权限ID列表
}

响应参数:

message AddRolePermissionResponse {
  // 空响应
}

状态码说明

本服务采用 gRPC 通用状态码（Canonical Status Codes），接口成功时直接返回响应消息；失败时通过错误返回，不在消息体中携带 code 或 message 字段。

常用 gRPC 状态码

状态码	含义	典型场景
OK	成功	调用成功返回业务数据
INVALID_ARGUMENT	参数不合法	校验失败、格式错误
FAILED_PRECONDITION	前置条件不满足	状态不允许本次操作
NOT_FOUND	资源不存在	用户/角色/权限等未找到
ALREADY_EXISTS	资源已存在	创建重复的唯一资源
UNAUTHENTICATED	未认证	Token 缺失或无效
PERMISSION_DENIED	无权限	无访问该资源的权限
RESOURCE_EXHAUSTED	资源耗尽	频控、配额用尽
ABORTED	冲突/并发冲突	乐观锁或并发更新冲突
OUT_OF_RANGE	超出范围	分页超界、偏移越界
UNIMPLEMENTED	未实现	方法未实现或版本不支持
INTERNAL	内部错误	未预期的服务端异常
UNAVAILABLE	服务不可用	依赖不可用、短暂性失败
DEADLINE_EXCEEDED	超时	请求超过截止时间
CANCELLED	已取消	客户端主动取消
DATA_LOSS	不可恢复的数据丢失	严重的数据损坏

客户端错误处理（Go 示例）

import (
    "context"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

resp, err := client.SomeRPC(context.Background(), req)
if err != nil {
    st, ok := status.FromError(err)
    if !ok {
        // 非 gRPC 错误
        // 记录并上报
        return
    }
    switch st.Code() {
    case codes.InvalidArgument:
        // 参数错误，提示用户修正
    case codes.Unauthenticated:
        // 引导重新登录或刷新 Token
    case codes.PermissionDenied:
        // 提示无权限
    case codes.NotFound:
        // 资源不存在
    case codes.DeadlineExceeded, codes.Unavailable:
        // 可重试类错误，提示稍后重试
    default:
        // 其他错误统一兜底
    }
    return
}
// 使用 resp 正常分支

服务端返回建议

• 参数/业务校验失败：返回 INVALID_ARGUMENT 或 FAILED_PRECONDITION
• 未登录/Token 过期：返回 UNAUTHENTICATED
• 无权限：返回 PERMISSION_DENIED
• 资源不存在/唯一冲突：返回 NOT_FOUND / ALREADY_EXISTS
• 可重试的依赖故障：返回 UNAVAILABLE
• 处理超时：返回 DEADLINE_EXCEEDED
• 未预期异常：返回 INTERNAL

说明：请通过 gRPC 错误来表达失败原因，不要在响应消息体中额外添加 code、message 字段。

使用示例

用户登录示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func main() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewAuthServiceClient(conn)

    // 创建登录请求
    loginRequest := &pb.LoginRequest{
        UserName: "admin",
        Password: "123456",
    }

    // 调用登录接口
    response, err := client.Login(context.Background(), loginRequest)
    if err != nil {
        log.Fatalf("登录失败: %v", err)
    }

    log.Printf("登录成功，访问令牌: %s", response.AccessToken)
    log.Printf("过期时间: %d", response.ExpiresAt)
}

用户注册示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func registerUser() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewAuthServiceClient(conn)

    // 创建注册请求
    registerRequest := &pb.RegisterRequest{
        UserName:           "newuser",
        Nickname:           "新用户",
        Mobile:             "13800138000",
        Email:              "newuser@example.com",
        Password:           "password123",
        OrganizationCode:   "ORG001",
        OrganizationName:   "示例组织",
    }

    // 调用注册接口
    response, err := client.RegisterUser(context.Background(), registerRequest)
    if err != nil {
        log.Fatalf("注册失败: %v", err)
    }

    log.Printf("注册成功，用户ID: %d", response.UserInfo.UserId)
}

获取用户列表示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func getUserList() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewUserServiceClient(conn)

    // 创建获取用户列表请求
    getUserListRequest := &pb.GetUserListRequest{
        AccessToken:      "your_access_token",
        DepartmentId:     "1",
        StartCreateTime:  "2024-01-01",
        EndCreateTime:    "2024-12-31",
    }

    // 调用获取用户列表接口
    response, err := client.GetUserList(context.Background(), getUserListRequest)
    if err != nil {
        log.Fatalf("获取用户列表失败: %v", err)
    }

    log.Printf("用户列表:")
    for _, user := range response.User {
        log.Printf("用户ID: %d, 用户名: %s, 昵称: %s", user.UserId, user.UserName, user.Nickname)
    }
}

添加权限示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func addPermission() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewPermissionServiceClient(conn)

    // 创建添加权限请求
    addPermissionRequest := &pb.AddPermissionRequest{
        AccessToken:     "your_access_token",
        Pid:            0, // 顶级权限
        Name:           "用户管理",
        Sign:           "user:manage",
        GroupName:      "系统管理",
        GroupNameDesc:  "系统管理相关权限",
    }

    // 调用添加权限接口
    response, err := client.AddPermission(context.Background(), addPermissionRequest)
    if err != nil {
        log.Fatalf("添加权限失败: %v", err)
    }

    log.Printf("添加权限成功")
}

获取部门列表示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func getDepartmentList() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDepartmentServiceClient(conn)

    // 创建获取部门列表请求
    getDepartmentListRequest := &pb.GetDepartmentListRequest{
        AccessToken: "your_access_token",
    }

    // 调用获取部门列表接口
    response, err := client.GetDepartmentList(context.Background(), getDepartmentListRequest)
    if err != nil {
        log.Fatalf("获取部门列表失败: %v", err)
    }

    log.Printf("部门列表:")
    for _, dept := range response.Department {
        log.Printf("部门ID: %d, 部门名称: %s, 父部门ID: %d", 
            dept.DepartmentId, dept.DepartmentName, dept.Pid)
    }
}

角色权限管理示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/grpc" // 替换为您的 proto 生成的包路径
)

func manageRolePermission() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewRoleServiceClient(conn)

    // 1. 创建角色
    addRoleRequest := &pb.AddRoleRequest{
        AccessToken: "your_access_token",
        RoleName:    "管理员",
    }

    roleResponse, err := client.AddRole(context.Background(), addRoleRequest)
    if err != nil {
        log.Fatalf("创建角色失败: %v", err)
    }
    log.Printf("创建角色成功")

    // 2. 为角色分配权限
    addRolePermissionRequest := &pb.AddRolePermissionRequest{
        AccessToken:   "your_access_token",
        RoleId:        1, // 假设角色ID为1
        PermissionIds: []int64{1, 2, 3}, // 权限ID列表
    }

    permissionResponse, err := client.AddRolePermission(context.Background(), addRolePermissionRequest)
    if err != nil {
        log.Fatalf("分配权限失败: %v", err)
    }
    log.Printf("分配权限成功")
}

Golang 项目设置

1. 安装依赖

# 安装 gRPC 相关依赖
go get google.golang.org/grpc
go get google.golang.org/protobuf
go get google.golang.org/grpc/cmd/protoc-gen-go-grpc
go get google.golang.org/protobuf/cmd/protoc-gen-go

2. 生成 Go 代码

# 生成 Go 代码（替换路径为您的实际路径）
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       user.proto

3. 项目结构示例

your_project/
├── proto/
│   └── user.proto
├── pb/
│   ├── user.pb.go
│   └── user_grpc.pb.go
├── client/
│   └── main.go
└── go.mod

4. go.mod 示例

module your_project

go 1.21

require (
    google.golang.org/grpc v1.60.1
    google.golang.org/protobuf v1.32.0
)

注意事项

1. 所有需要认证的接口都需要在请求中携带 access_token
2. 时间格式建议使用 ISO 8601 标准格式
3. 密码字段在传输时应该进行加密处理
4. 权限相关的操作需要相应的权限验证
5. 删除操作请谨慎使用，建议先进行确认
6. 示例中的 your_project/grpc 需要替换为您的实际 proto 生成的包路径
7. 服务端地址 localhost:50051 需要替换为实际的服务端地址
8. 建议在生产环境中使用 TLS 加密连接
9. 注意 proto 文件中的字段编号，确保与生成的代码一致
10. 空响应消息表示操作成功，无需返回额外数据