go-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go Code Review

Go代码审查

Structured code review process for Go. Reviews should be constructive, specific, and cite the relevant principle behind each finding.

针对Go语言的结构化代码审查流程。审查应具有建设性、针对性，并为每个问题引用相关的原则依据。

Review Process

审查流程

Execute these steps in order. For each finding, classify severity:

🔴 BLOCKER — Must fix before merge. Correctness, data loss, security.
🟡 WARNING — Should fix. Maintainability, idiomatic Go, clarity.
🟢 SUGGESTION — Consider improving. Style, naming, documentation.

按顺序执行以下步骤。针对每个问题，分类其严重程度：

🔴 阻塞问题 — 合并前必须修复。涉及正确性、数据丢失、安全问题。
🟡 警告问题 — 建议修复。涉及可维护性、Go语言惯用写法、代码清晰度。
🟢 优化建议 — 可考虑改进。涉及代码风格、命名、文档。

1. Correctness & Safety

1. 正确性与安全性

Error Handling

错误处理

Every error is checked. No blank identifier
```
_
```
discarding errors silently.

Errors are wrapped with context:

fmt.Errorf("fetch user %d: %w", id, err)

Error values compared with
```
errors.Is()
```
/
```
errors.As()
```
, never
```
==
```
.
No
```
panic
```
outside of
```
init()
```
or truly unrecoverable situations.
Errors handled exactly once — no log-and-return patterns.

所有错误均已检查。无使用空白标识符
```
_
```
静默丢弃错误的情况。

错误通过上下文进行包装：

fmt.Errorf("fetch user %d: %w", id, err)

。

使用
```
errors.Is()
```
/
```
errors.As()
```
比较错误值，绝不使用
```
==
```
。
除
```
init()
```
函数或真正无法恢复的场景外，禁止使用
```
panic
```
。
错误仅处理一次 — 避免“记录并返回”的模式。

Nil Safety

空值安全

Pointer receivers checked before dereference when nil is a valid state.
Map reads guarded or use comma-ok idiom.
Channel operations consider closed/nil channels.
Slice operations check bounds where relevant.

当空值是有效状态时，指针接收者在解引用前已检查。
读取map时进行保护或使用逗号-ok惯用写法。
通道操作考虑已关闭/空通道的情况。
切片操作在相关场景下检查边界。

Concurrency

并发

Shared mutable state protected by
```
sync.Mutex
```
or channels.
No goroutine leaks — every goroutine has a clear termination path.
Context propagation: all blocking calls accept and respect
```
context.Context
```
.
```
sync.WaitGroup
```
or
```
errgroup.Group
```
used for goroutine lifecycle.

共享可变状态通过
```
sync.Mutex
```
或通道进行保护。
无goroutine泄漏 — 每个goroutine都有明确的终止路径。
上下文传播：所有阻塞调用均接受并遵循
```
context.Context
```
。
使用
```
sync.WaitGroup
```
或
```
errgroup.Group
```
管理goroutine生命周期。

2. API Design

2. API设计

Exported functions have doc comments starting with the function name.
Accept interfaces, return concrete types.
Use functional options (
```
WithTimeout(d)
```
) over config structs for optional params.
Context is always the first parameter:
```
func Foo(ctx context.Context, ...)
```
.
Return
```
error
```
as the last return value.
Avoid
```
bool
```
parameters — prefer named types or options.

导出函数的文档注释以函数名开头。
接受接口类型，返回具体类型。
针对可选参数，使用函数式选项（
```
WithTimeout(d)
```
）而非配置结构体。
上下文始终作为第一个参数：
```
func Foo(ctx context.Context, ...)
```
。
将
```
error
```
作为最后一个返回值。
避免使用
```
bool
```
类型参数 — 优先使用命名类型或选项。

3. Idiomatic Go

3. Go语言惯用写法

Uses
```
:=
```
for local variables,
```
var
```
for zero-value intent.
No unnecessary
```
else
```
after return/continue/break.
Guard clauses and early returns reduce nesting.
```
defer
```
used for cleanup, placed right after resource acquisition.
```
range
```
used over manual index iteration where appropriate.
Struct literals use field names.
Interfaces defined at consumer, not producer.

局部变量使用
```
:=
```
，零值声明使用
```
var
```
。
在return/continue/break后无多余的
```
else
```
。
使用卫语句和提前返回减少嵌套层级。
```
defer
```
用于资源清理，且紧跟在资源获取之后。
合适的场景下使用
```
range
```
而非手动索引迭代。
结构体字面量使用字段名。
接口在消费端定义，而非生产端。

4. Package Structure

4. 包结构

Package names are short, lowercase, singular nouns.
No circular dependencies between packages.
```
internal/
```
used for non-public packages.
```
cmd/
```
contains main packages, one per binary.
Clear separation of concerns — no god packages.

包名简短、小写、单数名词。
包之间无循环依赖。
使用
```
internal/
```
存放非公开包。
```
cmd/
```
目录包含主包，每个二进制文件对应一个主包。
关注点清晰分离 — 无“上帝包”（包含过多功能的包）。

5. Testing

5. 测试

Test functions follow
```
TestXxx
```
naming convention.
Table-driven tests used for multiple input/output combinations.
Test helpers use
```
t.Helper()
```
for clean stack traces.
No test logic in
```
init()
```
— use
```
TestMain
```
when needed.
Tests use
```
testify/assert
```
or
```
testify/require
```
consistently, or stdlib only.
Edge cases covered: empty input, nil, zero values, max values.
```
t.Parallel()
```
used where safe.

测试函数遵循
```
TestXxx
```
命名规范。
针对多组输入/输出组合使用表驱动测试。
测试助手函数使用
```
t.Helper()
```
以获得清晰的堆栈跟踪。
不在
```
init()
```
中编写测试逻辑 — 必要时使用
```
TestMain
```
。
统一使用
```
testify/assert
```
或
```
testify/require
```
，或仅使用标准库。
覆盖边缘场景：空输入、空值、零值、最大值。
在安全的场景下使用
```
t.Parallel()
```
。

6. Documentation

6. 文档

All exported types, functions, and constants have doc comments.
Doc comments start with the name of the entity.
Package-level doc comment in
```
doc.go
```
for non-trivial packages.
Complex algorithms or business logic have inline comments explaining why.

所有导出类型、函数和常量均有文档注释。
文档注释以实体名称开头。
非简单包在
```
doc.go
```
中包含包级文档注释。
复杂算法或业务逻辑有行内注释解释原因。

7. Dependencies

7. 依赖

```
go.mod
```
has no replace directives in committed code (except monorepos).
No unused dependencies.
Dependencies are from well-maintained, reputable sources.
Indirect dependencies are understood and acceptable.

提交的代码中
```
go.mod
```
无replace指令（单体仓库除外）。
无未使用的依赖。
依赖来自维护良好、信誉良好的源。
间接依赖已被理解且可接受。

Review Output Format

审查输出格式

undefined

undefined

Code Review Summary

Files reviewed: <list> Overall assessment: APPROVE | REQUEST CHANGES | COMMENT

Findings

🔴 BLOCKER: <title>

File:
```
path/to/file.go:42
```
Issue: <what is wrong>
Why: <which principle or guideline>
Fix: <concrete suggestion>

File:
```
path/to/file.go:42
```
Issue: <what is wrong>
Why: <which principle or guideline>
Fix: <concrete suggestion>

🟡 WARNING: <title>

...

🟢 SUGGESTION: <title>

...

What's Done Well

undefined

undefined