测试、调试与日志

仓库包含 Controller、DTO、Middleware、Model、Service、Helper、迁移和基础服务测试。优先运行受影响包，再运行全量测试。

后端检查

gofmt -w app/service/example.go app/service/example_test.go
GOWORK=off go test ./app/service -run TestName -count=1
GOWORK=off go test ./...
GOWORK=off go vet ./...

并发相关改动在支持的环境中增加：

GOWORK=off go test -race ./...

不要运行会改写整个仓库的格式化命令；只格式化本次修改的 Go 文件。

前端检查

cd admin-webui
pnpm run check:type
pnpm run test:unit
pnpm run build:antd --filter='!./docs'

根包脚本实际名称是 check:type，不是旧文档中的 typecheck。应用包自身也提供 pnpm --filter @vben/web-antd typecheck。

API 调试

curl -i http://127.0.0.1:8081/health
curl -i http://127.0.0.1:8081/api/v1/short_links \
  -H 'Authorization: Bearer <test-token>' \
  -H 'X-Workspace-Id: 1'

排查顺序：HTTP 状态 → 响应 code/message → 服务日志 → 数据库/Redis健康 → 当前工作区与角色。签名请求还要核对服务器时间、请求 path、排序 JSON 和 Content-Type。

调试器

GOWORK=off dlv debug . -- start

断点优先放在 Controller 输入边界、Service 业务分支和 DAO 查询。短链跳转由中间件分发，不要只在普通 API 路由处寻找入口。

日志

日志接口是 gsr.Logger，实现来自 golog。当前代码使用字符串和 golog.Field：

logger := helper.GetHelper().GetLogger()
logger.Info("创建短链接", golog.Field("workspace_id", workspaceID))
logger.Error("创建失败: " + err.Error())

不要照搬旧文档中的 Zap 字段 API。APP_MODE=release 使用生产日志格式，非 release 使用开发格式。

严禁日志输出：密码、完整 JWT/API Token/App Secret、OIDC Client Secret、访问密码，以及不必要的完整 Query/请求体。操作日志已记录管理动作，新增中间件时避免重复持久化大 Body。

常见现象

现象	检查
401	Bearer 前缀、JWT/API Token 状态、签名四个头
403	X-Workspace-Id、成员状态和角色
短链 404	原始 Host、域名状态、短码、代理 Host 头
Redis 发号器启动失败	Redis 连通性、密码、ID_GENERATOR_DRIVER
管理端接口指错端口	.env.development 或 .env.local 的 VITE_GLOB_API_URL
新字段只在一种数据库工作	三方言迁移是否等价

相关章节：认证、FAQ。