Common Library

guoguo 项目的公共库，提供统一的错误码、响应结构、Proto 定义、工具函数等。

📦 包说明

包名	说明
errorcode	统一的错误码定义和消息
response	统一的 HTTP/RPC 响应结构
proto/common	公共的 Proto 消息定义（用于 gRPC）
constants	业务常量（登录类型、过期时间等）
utils/crypto	加密工具（密码哈希、验证）
utils/validator	验证工具（邮箱、用户名、密码格式）
utils/timeutil	时间工具（时间戳、格式化）

🚀 使用方法

1. 在其他项目中引入

编辑项目的 go.mod 文件：

require github.com/deep-memo/common v0.0.1

// 本地开发时使用 replace
replace github.com/deep-memo/common => ../common

然后执行：

go mod tidy

2. 使用错误码和响应

import (
    "github.com/deep-memo/common/errorcode"
    "github.com/deep-memo/common/response"
)

// 成功响应
resp := response.Success()

// 错误响应（使用默认消息）
resp := response.Error(errorcode.InvalidParams)

// 自定义错误消息
resp := response.ErrorWithMsg(errorcode.DatabaseError, "连接数据库失败")

// 判断响应是否成功
if resp.IsSuccess() {
    // 处理成功逻辑
}

3. 使用公共 Proto

在其他服务的 proto 文件中引用：

syntax = "proto3";

import "common.proto";

message LoginResponse {
  common.BaseResp baseResp = 1;
  common.AuthToken authToken = 2;
}

message ListUsersRequest {
  common.PageRequest page = 1;
}

message ListUsersResponse {
  common.BaseResp baseResp = 1;
  common.PageInfo pageInfo = 2;
  repeated common.UserInfo users = 3;
}

4. 使用常量

import "github.com/deep-memo/common/constants"

// 使用登录类型
loginType := constants.LoginTypeEmail

// 使用 Token 过期时间
expiresAt := time.Now().Unix() + constants.AccessTokenExpireSeconds

// 使用分页常量
pageSize := constants.DefaultPageSize

5. 使用加密工具

import "github.com/deep-memo/common/utils/crypto"

// 加密密码
hashedPassword, err := crypto.HashPassword("user_password")
if err != nil {
    // 处理错误
}

// 验证密码
isValid := crypto.CheckPassword("user_password", hashedPassword)

6. 使用验证工具

import "github.com/deep-memo/common/utils/validator"

// 验证邮箱格式
if !validator.IsValidEmail(email) {
    return response.Error(errorcode.InvalidParams)
}

// 验证用户名格式
if !validator.IsValidUsername(username) {
    return response.Error(errorcode.InvalidParams)
}

// 验证密码格式
if !validator.IsValidPassword(password) {
    return response.Error(errorcode.InvalidPassword)
}

// 验证登录类型
if !validator.IsValidLoginType(loginType) {
    return response.Error(errorcode.InvalidParams)
}

7. 使用时间工具

import "github.com/deep-memo/common/utils/timeutil"

// 获取当前 Unix 时间戳
now := timeutil.NowUnix()

// 格式化时间戳
timeStr := timeutil.FormatUnix(now)

// 判断是否过期
if timeutil.IsExpired(expiresAt) {
    return response.Error(errorcode.TokenExpired)
}

🔨 开发指南

生成 Proto 代码

当修改 proto/common.proto 后，需要重新生成代码：

cd proto
protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    common.proto

添加新的错误码

在 errorcode/errorcode.go 中添加：

const (
    NewErrorCode int32 = 50001 // 新的错误码
)

var ErrorMessage = map[int32]string{
    NewErrorCode: "new error message",
}

错误码分段规则

• 0: 成功
• 1xxxx: 系统级错误（数据库、缓存、RPC、网络等）
• 2xxxx: 请求相关错误（参数、格式、限流等）
• 3xxxx: 认证授权错误（Token、权限等）
• 4xxxx: 通用业务错误（资源不存在、冲突等）
• 5xxxx: 用户相关错误（用户不存在、密码错误等）

添加新的常量

在 constants/constants.go 中按类别添加：

const (
    // 新的业务常量
    NewConstant = "value"
)

添加新的工具函数

在 utils/ 下创建新的包或在现有包中添加函数。

📝 目录结构

common/
├── README.md                    # 本文档
├── go.mod                       # Go Module 定义
├── go.sum                       # 依赖版本锁定
├── errorcode/
│   └── errorcode.go            # 错误码定义
├── response/
│   └── response.go             # 响应结构
├── proto/
│   ├── common.proto            # Proto 定义
│   └── common/
│       ├── common.pb.go        # 生成的 Protobuf 代码
│       └── common_grpc.pb.go   # 生成的 gRPC 代码
├── constants/
│   └── constants.go            # 业务常量
└── utils/
    ├── crypto/
    │   └── password.go         # 密码加密工具
    ├── validator/
    │   └── validator.go        # 验证工具
    └── timeutil/
        └── time.go             # 时间工具

📋 依赖

• golang.org/x/crypto: 密码加密（bcrypt）
• google.golang.org/protobuf: Protocol Buffers
• google.golang.org/grpc: gRPC

🔄 版本管理

• v0.0.1: 初始版本
  • 基础错误码定义
  • 响应结构
  • 公共 Proto 定义
  • 常用工具函数

🤝 贡献指南

1. 所有错误码必须有注释说明
2. 新增 Proto 消息需要更新文档
3. 常量需要分类组织，添加注释
4. 工具函数需要考虑通用性和可复用性
5. 代码风格遵循 Go 官方规范

📄 License

MIT License