go

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go

This is a guide for how to develop applications and modules/libraries in Go.

Some of it is only applicable for applications, not modules used as libraries in other projects, such as database access and running a server.

这是一份Go应用程序及模块/库开发指南。

其中部分内容仅适用于应用程序，不适用于作为其他项目依赖库的模块，例如数据库访问和服务器运行相关内容。

Application structure

应用程序结构

Generally, I build web applications and libraries/modules.

These are the packages typically present in applications (some may be missing, which typically means I don't need them in the project).

```
main
```
: contains the main entry point of the application (in directory
```
cmd/app
```
)
```
model
```
: contains the domain model used throughout the other packages
```
sql
```
/
```
sqlite
```
/
```
postgres
```
: contains SQL database-related logic as well as database migrations (under subdirectory
```
migrations/
```
) and test fixtures (under subdirectory
```
testdata/fixtures/
```
). The database used is either SQLite or PostgreSQL.
```
sqltest
```
/
```
sqlitetest
```
/
```
postgrestest
```
: package used in testing, for setting up and tearing down test databases
```
s3
```
: logic for interacting with Amazon S3 or compatible object stores
```
s3test
```
: package used in testing, for setting up and tearing down test S3 buckets
```
llm
```
: clients for interacting with large language models (LLMs) and foundation models
```
llmtest
```
: package used in testing, for setting up LLM clients for testing
```
http
```
: HTTP handlers for the application
```
html
```
: HTML templates for the application, written with the gomponents library (see https://www.gomponents.com/llms.txt for how to use that if you need to)

我通常开发Web应用程序及库/模块。

以下是应用程序中通常会包含的包（部分包可能缺失，通常意味着项目中不需要它们）。

```
main
```
：包含应用程序的主入口（位于
```
cmd/app
```
目录下）
```
model
```
：包含所有其他包都会使用的领域模型
```
sql
```
/
```
sqlite
```
/
```
postgres
```
：包含SQL数据库相关逻辑，以及数据库迁移文件（位于
```
migrations/
```
子目录）和测试夹具（位于
```
testdata/fixtures/
```
子目录）。使用的数据库为SQLite或PostgreSQL。
```
sqltest
```
/
```
sqlitetest
```
/
```
postgrestest
```
：测试专用包，用于创建和销毁测试数据库
```
s3
```
：与Amazon S3或兼容对象存储交互的逻辑
```
s3test
```
：测试专用包，用于创建和销毁测试S3存储桶
```
llm
```
：与大语言模型（LLMs）和基础模型交互的客户端
```
llmtest
```
：测试专用包，用于为测试创建LLM客户端
```
http
```
：应用程序的HTTP处理器
```
html
```
：应用程序的HTML模板，使用gomponents库编写（如需使用可查看https://www.gomponents.com/llms.txt）

Code style

代码风格

Dependency injection

依赖注入

I make heavy use of dependency injection between components. This is typically done with private interfaces on the receiving side. Note the use of

userGetter

in this example:

package http

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"maragu.dev/httph"

	"model"
)

type UserResponse struct {
	Name string
}

type userGetter interface {
	GetUser(ctx context.Context, id model.ID) (model.User, error)
}

func User(r chi.Router, db userGetter) {
	r.Get("/user", httph.JSONHandler(func(w http.ResponseWriter, r *http.Request, _ any) (UserResponse, error) {
		id := r.URL.Query().Get("id")
		user, err := db.GetUser(r.Context(), model.ID(id))
		if err != nil {
			return UserResponse{}, httph.HTTPError{Code: http.StatusInternalServerError, Err: errors.New("error getting user")}
		}
		return UserResponse{Name: user.Name}, nil
	}))
}

我在组件之间大量使用依赖注入。通常通过接收端的私有接口实现。请注意以下示例中

userGetter

的使用：

package http

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"maragu.dev/httph"

	"model"
)

type UserResponse struct {
	Name string
}

type userGetter interface {
	GetUser(ctx context.Context, id model.ID) (model.User, error)
}

func User(r chi.Router, db userGetter) {
	r.Get("/user", httph.JSONHandler(func(w http.ResponseWriter, r *http.Request, _ any) (UserResponse, error) {
		id := r.URL.Query().Get("id")
		user, err := db.GetUser(r.Context(), model.ID(id))
		if err != nil {
			return UserResponse{}, httph.HTTPError{Code: http.StatusInternalServerError, Err: errors.New("error getting user")}
		}
		return UserResponse{Name: user.Name}, nil
	}))
}

Tests

测试

I write tests for most functions and methods. I almost always use subtests with a good description of whats is going on and what the expected result is.

Here's an example:

package example

type Thing struct {}

func (t *Thing) DoSomething() (bool, error) {
	return true, nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	t.Run("should do something and return a nil error", func(t *testing.T) {
		thing := &example.Thing{}

		ok, err := thing.DoSomething()
		is.NotError(t, err)
		is.True(t, ok)
	})
}

Sometimes I use table-driven tests:

package example

import "errors"

type Thing struct {}

var ErrChairNotSupported = errors.New("chairs not supported")

func (t *Thing) DoSomething(with string) error {
	if with == "chair" {
		return ErrChairNotSupported
	}
	return nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	tests := []struct {
		name     string
		input    string
		expected error
	}{
		{name: "should do something with the table and return a nil error", input: "table", expected: nil},
		{name: "should do something with the chair and return an ErrChairNotSupported", input: "chair", expected: example.ErrChairNotSupported},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			thing := &example.Thing{}

			err := thing.DoSomething(test.input)
			if test.expected != nil {
				is.Error(t, test.expected, err)
			} else {
				is.NotError(t, err)
			}
		})
	}
}

I prefer integration tests with real dependencies over mocks, because there's nothing like the real thing. Dependencies are typically run in Docker containers. You can assume the dependencies are running when running tests.

It makes sense to use mocks when the important part of a test isn't the dependency, but it plays a smaller role. But for example, when testing database methods, a real underlying database should be used.

I use test assertions with the module

maragu.dev/is

. Available functions:

is.True

is.Equal

is.Nil

is.NotNil

is.EqualSlice

is.NotError

is.Error

. All of these take an optional message as the last parameter.

Since tests are shuffled, don't rely on test order, even for subtests.

Every time the

postgrestest.NewDatabase(t)

sqlitetest.NewDatabase(t)

test helpers are called, the database is in a clean state (no leftovers from other tests etc.).

You can use database fixtures for tests. Prefer these for test data setups when multiple tests rely on the same or very similar data, so that every test doesn't have to set up the same data. They are in

sqlite/testdata/fixtures

postgres/testdata/fixtures

. Use them with

sqlitetest.NewDatabase(t, sqlitetest.WithFixtures("fixture one", "fixture two"))

. They are applied in the order given.

Test helper functions should call

testing.T.Helper()

In tests, use

t.Context()

instead of

context.Background()

, and always use it inline instead of pulling out into a

ctx

variable.

我会为大多数函数和方法编写测试。我几乎总会使用子测试，并清晰描述测试内容和预期结果。

Here's an example:

package example

type Thing struct {}

func (t *Thing) DoSomething() (bool, error) {
	return true, nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	t.Run("should do something and return a nil error", func(t *testing.T) {
		thing := &example.Thing{}

		ok, err := thing.DoSomething()
		is.NotError(t, err)
		is.True(t, ok)
	})
}

有时候我会使用表驱动测试：

package example

import "errors"

type Thing struct {}

var ErrChairNotSupported = errors.New("chairs not supported")

func (t *Thing) DoSomething(with string) error {
	if with == "chair" {
		return ErrChairNotSupported
	}
	return nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	tests := []struct {
		name     string
		input    string
		expected error
	}{
		{name: "should do something with the table and return a nil error", input: "table", expected: nil},
		{name: "should do something with the chair and return an ErrChairNotSupported", input: "chair", expected: example.ErrChairNotSupported},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			thing := &example.Thing{}

			err := thing.DoSomething(test.input)
			if test.expected != nil {
				is.Error(t, test.expected, err)
			} else {
				is.NotError(t, err)
			}
		})
	}
}

相较于模拟对象，我更喜欢使用真实依赖的集成测试，因为真实环境是无可替代的。依赖通常运行在Docker容器中。运行测试时可默认依赖已启动。

当测试的核心并非依赖项，且依赖仅起次要作用时，使用模拟对象是合理的。但例如在测试数据库方法时，应使用真实的底层数据库。

我使用

maragu.dev/is

模块进行测试断言。可用函数包括：

is.True

、

is.Equal

、

is.Nil

、

is.NotNil

、

is.EqualSlice

、

is.NotError

、

is.Error

。所有这些函数都支持将可选消息作为最后一个参数。

由于测试会随机排序，请勿依赖测试执行顺序，即使是子测试也不例外。

每次调用

postgrestest.NewDatabase(t)

sqlitetest.NewDatabase(t)

测试工具函数时，数据库都会处于干净状态（无其他测试遗留数据等）。

你可以为测试使用数据库夹具。当多个测试依赖相同或高度相似的数据时，建议使用夹具来设置测试数据，这样每个测试就无需重复设置相同数据。夹具位于

sqlite/testdata/fixtures

postgres/testdata/fixtures

目录下。可通过

sqlitetest.NewDatabase(t, sqlitetest.WithFixtures("fixture one", "fixture two"))

来使用，夹具会按传入顺序应用。

测试工具函数应调用

testing.T.Helper()

。

在测试中，使用

t.Context()

而非

context.Background()

，并始终内联使用，不要将其赋值给

ctx

变量。

Miscellaneous

其他注意事项

Variable naming:
- ```
req
```
  for requests,
```
res
```
  for responses

There are SQL helpers available, at

Database.H.Select

Database.H.Exec

Database.H.Get

Database.H.InTx

Use the
```
any
```
builtin in Go instead of
```
interface{}
```
There's an alias for
```
sql.ErrNoRows
```
from stdlib at
```
maragu.dev/glue/sql.ErrNoRows
```
, so you don't have to import both
All HTML buttons need the
```
cursor-pointer
```
CSS class
SQLite time format is always a string returned by
```
strftime('%Y-%m-%dT%H:%M:%fZ')
```
. Use
```
maragu.dev/glue/model.Time
```
(usually aliased in
```
model.Time
```
in the project) instead of stdlib
```
time.Time
```
when working with the database.
Remember that private functions in Go are package-level, so you can use them across files in the same package
Documentation must follow the Go style of having the identifier name be the first word of the sentence, and then completing the sentence without repeating itself. Example: "// SearchProducts using the given search query and result limit." NOT: "// SearchProducts searches products using the given search query and result label."
Package-level identifiers must begin with lowercase by default, i.e. have package-level visibility, to make the API surface area towards other packages smaller.
Use
```
fmt.Sprint
```
when converting arbitrary values to strings, instead of functions from
```
strconv
```
.
Use
```
new()
```
(available since Go 1.26) instead of any pointer functions for making pointers to literals.

变量命名：
- 请求用
```
req
```
  ，响应用
```
res
```

提供以下SQL工具函数：

Database.H.Select

、

Database.H.Exec

、

Database.H.Get

、

Database.H.InTx

使用Go内置的
```
any
```
类型替代
```
interface{}
```
```
maragu.dev/glue/sql.ErrNoRows
```
是标准库
```
sql.ErrNoRows
```
的别名，因此无需同时导入两者
所有HTML按钮都需要添加
```
cursor-pointer
```
CSS类
SQLite的时间格式始终为
```
strftime('%Y-%m-%dT%H:%M:%fZ')
```
返回的字符串。操作数据库时，请使用
```
maragu.dev/glue/model.Time
```
（项目中通常别名为
```
model.Time
```
）而非标准库的
```
time.Time
```
请记住，Go中的私有函数是包级别的，因此可在同一包的不同文件中使用
文档必须遵循Go的风格：标识符名称作为句子的第一个单词，然后完成句子且不重复标识符。示例："// SearchProducts using the given search query and result limit." 而非："// SearchProducts searches products using the given search query and result label."
包级标识符默认必须以小写开头，即仅具有包级可见性，以减少对其他包暴露的API范围
将任意值转换为字符串时，使用
```
fmt.Sprint
```
而非
```
strconv
```
包中的函数
创建字面量的指针时，使用
```
new()
```
（Go 1.26及以上版本可用）而非其他指针函数

Testing, linting, evals

测试、代码检查与评估

Run

make test

go test -shuffle on ./...

to run all tests. To run tests in just one package, use

go test -shuffle on ./path/to/package

. To run a specific test, use

go test ./path/to/package -run TestName

Run

make lint

golangci-lint run

to run linters. They should always be run on the package/directory level, it won't work with single files.

Run

make eval

go test -shuffle on -run TestEval ./...

to run LLM evals.

Run

make fmt

to format all code in the project, which is useful as a last finishing touch.

You can access the database by using

psql

sqlite3

in the shell.

运行

make test

或

go test -shuffle on ./...

来执行所有测试。仅运行单个包的测试可使用

go test -shuffle on ./path/to/package

。运行特定测试可使用

go test ./path/to/package -run TestName

。

运行

make lint

或

golangci-lint run

来执行代码检查。代码检查应始终在包/目录级别运行，无法针对单个文件执行。

运行

make eval

或

go test -shuffle on -run TestEval ./...

来执行LLM评估。

运行

make fmt

来格式化项目中所有代码，这是完成代码编写后的收尾步骤。

可在终端中使用

psql

或

sqlite3

访问数据库。

Documentation

文档

You can generally look up documentation for a Go module using

go doc

with the module name. For example,

go doc net/http

for something in the standard library, or

go doc maragu.dev/gai

for a third-party module. You can also look up more specific documentation for an identifier with something like

go doc maragu.dev/gai.ChatCompleter

, for the

ChatCompleter

interface.

通常可使用

go doc

加模块名来查看Go模块的文档。例如，查看标准库内容可使用

go doc net/http

，查看第三方模块可使用

go doc maragu.dev/gai

。还可查看特定标识符的文档，例如

go doc maragu.dev/gai.ChatCompleter

可查看

ChatCompleter

接口的文档。

Checking apps in a browser

在浏览器中检查应用

You can assume the app is running and available in a browser using the Chrome Dev Tools MCP tool. It auto-reloads on code changes so you don't have to. Log output from the running application is in

app.log

in the project root.

可默认应用已启动，并可通过Chrome Dev Tools MCP工具在浏览器中访问。代码变更时应用会自动重载，无需手动操作。运行中应用的日志输出位于项目根目录的

app.log

文件中。