# gozero-utils

**Repository Path**: yanwc/gozero-utils

## Basic Information

- **Project Name**: gozero-utils
- **Description**: gozero常用错误，消息返回值
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-27
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gozero-utils

基于 go-zero 框架的通用工具库，提供错误处理、HTTP 响应、JWT 认证、缓存等常用功能。

## 安装

```bash
go get gitee.com/yanwc/gozero-utils@latest
```

## 模块说明

| 模块 | 说明 |
|------|------|
| `api` | HTTP 响应处理 |
| `errx` | 错误码定义和错误类型 |
| `httpx` | HTTP 客户端和用户上下文 |
| `jwtx` | JWT Token 生成和验证 |
| `gormx` | GORM 数据库工具 |
| `cachex` | 缓存工具 |
| `rpcx` | RPC 调用工具 |

## 错误处理机制

### HTTP 响应状态码规则

`api.HttpResult` 函数根据错误类型自动选择 HTTP 状态码：

| 错误类型 | HTTP 状态码 | 说明 |
|----------|-------------|------|
| `nil` | 200 | 成功响应 |
| `*errx.Error` (BIZ) | 200 | 业务错误，前端显示错误消息 |
| `*errx.Error` (TOKEN_EXPIRE) | 401 | Token 过期，触发重新登录 |
| `*errx.Error` (其他) | 200 | 自定义错误码 |
| gRPC 错误 | 200/401 | 根据 gRPC 状态码映射 |
| `errors.New()` 普通错误 | **400** | 请求参数错误，前端显示错误消息 |

### 使用示例

```go
import (
    "errors"
    "gitee.com/yanwc/gozero-utils/errx"
    "gitee.com/yanwc/gozero-utils/api"
)

// 方式1: 普通错误 - 返回 HTTP 400
func (l *Logic) Create(req *types.Req) (resp *types.Resp, err error) {
    if req.Name == "" {
        return nil, errors.New("名称不能为空")  // HTTP 400
    }
    // ...
}

// 方式2: 业务错误 - 返回 HTTP 200，code=10000
func (l *Logic) Update(req *types.Req) (resp *types.Resp, err error) {
    if !hasPermission {
        return nil, errx.NewBiz("无权限操作")  // HTTP 200, code: 10000
    }
    // ...
}

// 方式3: 预定义错误码
func (l *Logic) Delete(id int64) error {
    if id <= 0 {
        return errx.New(errx.PARAM_REQUIRED)  // HTTP 200, code: 10011
    }
    // ...
}
```

### 前端错误处理

前端 axios 拦截器应处理 400 状态码：

```typescript
axiosInstance.interceptors.response.use(
  (res) => res,
  (error: AxiosError) => {
    if (error.status === 401) {
      // Token 过期，跳转登录
      userStore.logout();
    } else if (error.status === 400 && error.response?.data) {
      // 参数校验错误，显示后端返回的消息
      const data = error.response.data as IResponse;
      ElMessage.error(data.message);
    } else {
      ElMessage.error(error.message);
    }
    return Promise.reject(error);
  }
);
```

### 错误码定义

```go
const (
    OK      Code = 200     // 成功
    BIZ     Code = 100_00  // 业务错误
    SERVER  Code = 100_01  // 服务器错误
    REUQEST_PARAM Code = 100_02  // 请求参数错误
    TOKEN_EXPIRE  Code = 100_03  // Token过期
    DB            Code = 100_05  // 数据库错误
    DB_NOT_FOUND  Code = 100_09  // 记录不存在
    UNAUTHORIZED  Code = 100_31  // 未授权
    // ... 更多错误码见 errx/code.go
)
```

## 版本历史

### v1.3.80
- **feat**: 普通错误（`errors.New()`）返回 HTTP 400 状态码，而非 500
- 优化前端错误提示体验，表单校验失败时显示具体错误消息

### v1.3.78
- 之前的稳定版本

## License

MIT