refactor: 后端代码质量优化 - 复用公共库、使用标准库、类型安全错误判断
## 高优先级修复 - stats_service_impl: 使用 strings.SplitN 替代错误的索引分割 - provider_handler: 使用 errors.Is(err, gorm.ErrDuplicatedKey) 替代字符串匹配 - client: 重写 isNetworkError 使用 errors.As/Is 类型安全判断 - proxy_handler: 使用 encoding/json 标准库解析 JSON(extractModelName、isStreamRequest) ## 中优先级修复 - stats_handler: 添加 parseDateParam 辅助函数消除重复日期解析 - pkg/errors: 新增 ErrRequestCreate/Send/ResponseRead 错误类型和 WithCause 方法 - client: 使用结构化错误替代 fmt.Errorf - ConversionEngine: logger 依赖注入,替换所有 zap.L() 调用 ## 低优先级修复 - encoder: 删除 joinStrings,使用 strings.Join - adapter: 删除 modelInfoRegex 正则,使用 isModelInfoPath 字符串函数 ## 文档更新 - README.md: 添加公共库使用指南和编码规范章节 - specs: 同步 delta specs 到 main specs(error-handling、structured-logging、request-validation) ## 归档 - openspec/changes/archive/2026-04-20-refactor-backend-code-quality/
This commit is contained in:
@@ -329,3 +329,61 @@ make lint
|
||||
### 环境要求
|
||||
|
||||
- Go 1.26 或更高版本
|
||||
|
||||
## 公共库使用指南
|
||||
|
||||
### pkg/errors — 结构化错误
|
||||
|
||||
使用预定义的错误类型,配合 `errors.Is` / `errors.As` 判断错误:
|
||||
|
||||
```go
|
||||
import (
|
||||
"errors"
|
||||
pkgErrors "nex/backend/pkg/errors"
|
||||
)
|
||||
|
||||
// 使用预定义错误
|
||||
return pkgErrors.ErrRequestSend.WithCause(err)
|
||||
|
||||
// 判断错误类型
|
||||
var appErr *pkgErrors.AppError
|
||||
if errors.As(err, &appErr) {
|
||||
// appErr.Code, appErr.HTTPStatus, appErr.Message
|
||||
}
|
||||
```
|
||||
|
||||
可用函数:`NewAppError`、`Wrap`、`WithContext`、`WithMessage`、`AsAppError`
|
||||
|
||||
预定义错误:`ErrModelNotFound`、`ErrProviderNotFound`、`ErrInvalidRequest`、`ErrRequestCreate`、`ErrRequestSend`、`ErrResponseRead` 等
|
||||
|
||||
### pkg/logger — 日志系统
|
||||
|
||||
使用依赖注入模式,构造函数接受 `*zap.Logger` 参数,nil 时回退到 `zap.L()`:
|
||||
|
||||
```go
|
||||
func NewMyService(repo Repository, logger *zap.Logger) *MyService {
|
||||
if logger == nil {
|
||||
logger = zap.L()
|
||||
}
|
||||
return &MyService{repo: repo, logger: logger}
|
||||
}
|
||||
```
|
||||
|
||||
禁止直接在业务代码中使用 `zap.L()` 全局 logger,应通过构造函数注入。
|
||||
|
||||
### pkg/validator — 请求验证
|
||||
|
||||
```go
|
||||
import "nex/backend/pkg/validator"
|
||||
|
||||
v := validator.Get()
|
||||
err := v.Validate(myStruct)
|
||||
```
|
||||
|
||||
## 编码规范
|
||||
|
||||
- **JSON 解析**:使用 `encoding/json` 标准库(`json.Unmarshal` / `json.Marshal`),不手动扫描字节
|
||||
- **字符串拼接**:使用 `strings.Join`,不手写循环拼接
|
||||
- **错误判断**:使用 `errors.Is` / `errors.As`,不使用字符串匹配(`strings.Contains(err.Error(), ...)`)
|
||||
- **日志使用**:通过依赖注入 `*zap.Logger`,不直接调用 `zap.L()`
|
||||
- **字符串分割**:使用 `strings.SplitN(key, "/", 2)` 等精确分割,不使用索引切片
|
||||
|
||||
Reference in New Issue
Block a user