代码Apr 8, 2026·2 min read

Nuxt + Go-Zero Quality Audit Skill — 30 Checks from 250 Real Bugs

Production-tested quality check skill for Nuxt SSR + Go-Zero + MySQL projects. 30 automated checks across 7 dimensions (security, race conditions, transactions, frontend SSR, dependencies, API contracts, ops) — distilled from 10 rounds of Codex audit that found ~250 real issues in a live SaaS product.

HE
henuwangkai · Community
Quick Use

Use it first, then decide how deep to go

This block should tell both the user and the agent what to copy, install, and apply first.

TokRepo 技术质量检测

TokRepo 项目定期质量检测 skill。基于 10 轮 Codex 审计发现的 ~250 个问题提炼的检查清单。

触发方式

/tokrepo-quality-check           # 全量检测
/tokrepo-quality-check security  # 只跑安全检测
/tokrepo-quality-check deps      # 只跑依赖检测
/tokrepo-quality-check race      # 只跑并发安全检测
/tokrepo-quality-check frontend  # 只跑前端检测

项目信息

  • 路径: <project_root>/
  • 后端: Go-Zero + GORM, backend/
  • 前端: Nuxt 4 SSR, frontend-nuxt/
  • CLI: cli/bin/tokrepo.js
  • MCP: mcp-server/bin/server.js

执行流程

收到 /tokrepo-quality-check [scope] 后：

  1. 读取 references/checklist.md 获取完整检查清单
  2. 根据 scope 参数决定执行哪些检查组（默认全部）
  3. 逐项执行检查，用 Grep/Read/Bash 验证
  4. 输出报告，格式见下方

报告格式

## TokRepo 质量检测报告 — {date}

### 总览
| 检查组 | 通过 | 失败 | 跳过 |
|--------|------|------|------|
| ...    | ...  | ...  | ...  |

### 失败项详情
#### [{severity}] {check_id}: {description}
- 文件: {file_path}:{line}
- 现状: {what_was_found}
- 应该: {what_is_expected}
- 修复: {how_to_fix}

### 通过项（折叠）
- [PASS] SEC-01: ...
- [PASS] SEC-02: ...

严重级别

  • CRITICAL: 可被外部利用的安全漏洞
  • HIGH: 数据一致性/可靠性风险
  • MEDIUM: 性能/可维护性问题
  • LOW: 代码质量/规范问题

TokRepo 质量检查清单

基于 10 轮 Codex 审计（~250 个问题）提炼。每个检查项包含：ID、严重级别、检查方法、通过标准。

一、安全检测 (SEC)

SEC-01 [CRITICAL] 凭证不入库

# 检查方法：在 git tracked files 中搜索敏感模式
git ls-files | xargs grep -lE '(password|secret|dsn|token).*=' 2>/dev/null | grep -vE '(\.example|types\.go|model\.go|mock|test|\.md|\.json|config\.py)'

通过标准: 无匹配，或匹配文件仅包含环境变量读取（os.Getenv/process.env）

SEC-02 [CRITICAL] .gitignore 覆盖敏感文件

# 检查 .gitignore 是否包含关键排除
grep -c 'api\.yaml\|\.env' .gitignore

通过标准: .env 和 backend/etc/api.yaml 都在 .gitignore 中

SEC-03 [CRITICAL] JWT 强制签名算法

# 检查 authenticate_middleware.go 是否强制 HMAC
grep -n 'SigningMethod' backend/internal/middleware/authenticate_middleware.go

通过标准: 存在 SigningMethodHMAC 或 alg 检查

SEC-04 [CRITICAL] API token hash 存储

# 检查是否用 SHA-256 hash
grep -rn 'ApiTokenHash\|HashApiToken' backend/internal/

通过标准: 认证中间件用 hash 查找，generate_token 存 hash

SEC-05 [HIGH] share_token 不在列表接口泄露

# 检查 helper.go 列表 builder
grep -A2 'ShareToken' backend/internal/logic/tokenboard/workflows/helper.go

通过标准: buildWorkflowItemsLight 和 buildWorkflowItemLight 中 ShareToken 为空字符串或不设置；buildWorkflowItem 仅对 owner 返回

SEC-06 [HIGH] OAuth 回调检查 HTTP 状态码

grep -n 'StatusCode\|statusCode\|status_code' backend/internal/logic/tokenboard/auth/callback_logic.go

通过标准: token exchange 和 userinfo 请求都检查了 HTTP 状态码

SEC-07 [HIGH] 私有数据不泄露到公开接口

# stats 和 heatmap 应过滤 visibility
grep -n 'visibility' backend/internal/logic/tokenboard/users/get_user_stats_logic.go
grep -n 'visibility' backend/internal/logic/tokenboard/users/get_user_heatmap_logic.go

通过标准: 两个文件的查询都包含 visibility = 1

SEC-08 [HIGH] SSR raw 代理不覆盖缓存头

grep -n 'Cache-Control\|Access-Control' frontend-nuxt/server/routes/raw/\[id\].ts

通过标准: 认证请求返回 private, no-store，不设置 Access-Control-Allow-Origin: *

SEC-09 [MEDIUM] Rate limit IP 提取正确

grep -n 'X-Forwarded-For' backend/internal/middleware/ratelimit_middleware.go

通过标准: 取逗号分割后的第一个 IP，不取整个字符串

SEC-10 [MEDIUM] CSP 安全头已配置

grep -n 'Content-Security-Policy\|X-Frame-Options\|X-Content-Type-Options' frontend-nuxt/nuxt.config.ts

通过标准: 至少包含 CSP、X-Frame-Options、X-Content-Type-Options

二、并发安全检测 (RACE)

RACE-01 [CRITICAL] Fork 事务内去重

grep -B5 -A5 'existingFork\|existing.*Fork' backend/internal/logic/tokenboard/workflows/fork_workflow_logic.go

通过标准: 去重检查在 Transaction 回调内部，不在外面

RACE-02 [CRITICAL] Upsert 查找+创建在同一事务

grep -n 'Transaction\|updateExistingTx\|createNewTx' backend/internal/logic/tokenboard/push/upsert_logic.go

通过标准: lookup + create/update 包在同一个 Transaction 中

RACE-03 [HIGH] Update 加行锁

grep -n 'clause.Locking\|FOR UPDATE' backend/internal/logic/tokenboard/workflows/update_workflow_logic.go

通过标准: 存在 clause.Locking{Strength: "UPDATE"}

RACE-04 [HIGH] Delete 加行锁

grep -n 'clause.Locking\|FOR UPDATE' backend/internal/logic/tokenboard/workflows/delete_workflow_logic.go

通过标准: 存在 clause.Locking{Strength: "UPDATE"}

RACE-05 [HIGH] Vote 加行锁

grep -n 'clause.Locking\|FOR UPDATE' backend/internal/logic/tokenboard/workflows/vote_workflow_logic.go

通过标准: 存在 clause.Locking{Strength: "UPDATE"}

RACE-06 [HIGH] Follow toggle 单事务

grep -c 'Transaction' backend/internal/logic/tokenboard/users/toggle_follow_logic.go

通过标准: 检查+删除/创建 在同一个事务中（≤1 个 Transaction 调用 or check 在 tx 内）

RACE-07 [HIGH] Transfer 权限检查在事务内

# 检查 ownership 验证是否在 Transaction 回调内
grep -B3 'UserId != sourceUserId' backend/internal/logic/tokenboard/workflows/transfer_workflow_logic.go

通过标准: 权限检查在 Transaction(func(tx 内部

RACE-08 [HIGH] 唯一约束存在

# 在数据库 migration 或 init.sql 中检查
grep -rn 'UNIQUE\|uk_' database/

通过标准: tb_forks(user_id,source_workflow_id)、tb_follows(follower_id,following_id)、tb_votes(workflow_id,user_id) 都有唯一约束

三、事务可靠性检测 (TX)

TX-01 [HIGH] 事务内写操作检查 .Error

# 搜索事务内没有 error check 的写操作
grep -n 'tx\.Create\|tx\.Update\|tx\.Delete\|tx\.Model' backend/internal/logic/tokenboard/ -r | grep -v '\.Error'

通过标准: 所有事务内写操作都检查了 .Error（允许通知类写入不检查）

TX-02 [MEDIUM] 计数器用原子操作

# 搜索计数器更新是否用 gorm.Expr
grep -rn 'fork_count\|vote_count\|workflow_count\|follower_count\|comment_count' backend/internal/logic/ | grep 'Update' | grep -v 'Expr'

通过标准: 所有计数器增减都用 gorm.Expr("field + 1") 或 gorm.Expr("GREATEST(field - 1, 0)")

TX-03 [MEDIUM] 计数器不会变负

grep -rn 'GREATEST.*0\)' backend/internal/logic/

通过标准: 所有递减操作都用 GREATEST(field - 1, 0)

四、前端检测 (FE)

FE-01 [HIGH] SSR 状态不泄露

# 检查 composables 中是否有模块级 reactive/ref（应该用 useState）
grep -rn '^const.*= reactive\|^const.*= ref\|^let.*= reactive\|^let.*= ref' frontend-nuxt/composables/

通过标准: 无匹配。所有 composable 状态应使用 useState()

FE-02 [HIGH] SSR 请求用内部地址

grep -n 'apiInternal\|import.meta.server' frontend-nuxt/utils/request.ts

通过标准: SSR 环境下使用 apiInternal（localhost），CSR 使用 apiBase（公网）

FE-03 [MEDIUM] Auth 错误不误杀

grep -A5 'catch' frontend-nuxt/composables/useAuth.ts | grep -E '401|403|status'

通过标准: fetchUser 的 catch 块区分 401/403（清 auth）和其他错误（保留 auth state）

FE-04 [MEDIUM] Modal 可访问性

grep -n 'role="dialog"\|aria-modal\|aria-labelledby' frontend-nuxt/components/ConfirmModal.vue

通过标准: 包含 role="dialog"、aria-modal="true"、aria-labelledby

FE-05 [MEDIUM] localStorage 异常处理

grep -B1 -A3 'localStorage' frontend-nuxt/plugins/posthog.client.ts

通过标准: 所有 localStorage 读写都在 try/catch 中

FE-06 [LOW] 用户输入 URL 编码

grep -n 'user_nickname\|user_name' frontend-nuxt/components/CommentSection.vue | grep -v 'encodeURIComponent'

通过标准: URL 中使用的用户名都经过 encodeURIComponent

五、依赖检测 (DEP)

DEP-01 [CRITICAL] Go 关键依赖无已知漏洞

grep 'google.golang.org/grpc' backend/go.mod

通过标准: grpc >= v1.79.3

DEP-02 [HIGH] Go 依赖版本

grep -E '(golang.org/x/net|go.opentelemetry.io/otel )' backend/go.mod

通过标准: x/net >= v0.48.0, otel >= v1.36.0

DEP-03 [HIGH] 前端无 high 漏洞

cd frontend-nuxt && npm audit --audit-level=high 2>&1 | tail -5

通过标准: found 0 vulnerabilities 或无 high/critical

DEP-04 [LOW] CLI/MCP 有 lockfile

ls -la cli/package-lock.json mcp-server/package-lock.json

通过标准: 两个文件都存在

六、API 契约检测 (API)

API-01 [MEDIUM] .api 文件与 types.go 字段对齐

# 对比 workflows.api 和 types.go 中 TbWorkflowItem 的字段数
grep -c 'json:"' backend/apilist/tokenboard/workflows/workflows.api | head -1
grep -c 'json:"' backend/internal/types/types.go | head -1

通过标准: 关键类型（TbWorkflowItem, TbPushCreateRequest）字段数一致

API-02 [MEDIUM] Push upsert/diff 路由已定义

grep -n 'upsert\|diff' backend/apilist/tokenboard/push/push.api

通过标准: upsert 和 diff 路由都存在

API-03 [LOW] LangType 字段填充

grep -c 'LangType' backend/internal/logic/tokenboard/workflows/helper.go

通过标准: >= 3（三个 builder 函数都填充）

七、运维检测 (OPS)

OPS-01 [HIGH] AutoMigrate 不在生产跑

grep -A3 'AutoMigrate' backend/internal/svc/service_context.go

通过标准: 被 APP_ENV != "production" 条件包裹

OPS-02 [MEDIUM] Migration 幂等

grep -c 'IF NOT EXISTS\|information_schema' database/*.sql

通过标准: 每个 migration 文件都有幂等检查

OPS-03 [MEDIUM] 部署脚本有回滚机制

grep -n 'bak\|rollback\|backup' deploy.sh

通过标准: 编译前备份旧二进制，失败时有回滚提示

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.
◈Home🔍Search👤Me