go-functions

Go 函数设计

资源路由

• references/SIGNATURES.md - 设计参数、返回值、命名返回值或签名可读性时阅读。
• references/PRINTF-STRINGER.md - 使用 fmt 格式化动词、Stringer、GoStringer、Formatter 或 Printf 风格的函数命名时阅读。

此技能不适用的情况：对于函数选项构造函数（WithTimeout、WithLogger），请参阅 go-functional-options。对于错误返回约定，请参阅 go-error-handling。对于函数和方法命名，请参阅 go-naming。

---

函数分组与排序

按以下规则组织文件中的函数：

1. 函数按大致调用顺序排序
2. 函数按接收者分组
3. 在 struct/const/var 定义之后，导出函数优先出现
4. NewXxx/newXxx 构造函数紧接类型定义之后出现
5. 普通工具函数放在文件靠后的位置

type something struct{ ... }

func newSomething() *something { return &something{} }

func (s *something) Cost() int { return calcCost(s.weights) }

func (s *something) Stop() { ... }

func calcCost(n []int) int { ... }

---

函数签名

尽可能将签名放在一行内。必须换行时，将所有参数各放一行，并在末尾加逗号：

func (r *SomeType) SomeLongFunctionName(
    foo1, foo2, foo3 string,
    foo4, foo5, foo6 int,
) {
    foo7 := bar(foo1)
}

对于含义不明确的参数，添加 /* name */ 注释；更好的做法是用自定义类型替换裸 bool 参数。

---

指向接口的指针

你几乎不需要指向接口的指针。将接口作为值传递——底层数据仍然可以是指针。

// Bad: pointer to interface
func process(r *io.Reader) { ... }

// Good: pass the interface value
func process(r io.Reader) { ... }

---

Printf 与 Stringer

Printf 风格的函数名

接受格式字符串的函数应以 f 结尾，以便 go vet 支持。 在 Printf 调用之外使用格式字符串时，将其声明为 const。

在为日志或错误消息格式化字符串时，优先使用 %q，而不是 %s 配合手动加引号——它会安全地转义特殊字符并加上引号：

return fmt.Errorf("unknown key %q", key) // produces: unknown key "foo\nbar"

设计含有 3 个或更多可选参数的构造函数时，请参阅 go-functional-options。

---

快速参考

主题	规则
文件顺序	类型 -> 构造函数 -> 导出函数 -> 未导出函数 -> 工具函数
签名换行	所有参数各放一行，末尾加逗号
裸参数	添加 /* name */ 注释或使用自定义类型
指向接口的指针	几乎不需要；按值传递接口
Printf 函数名	以 f 结尾，以便 go vet 支持

---

相关技能

• 错误返回：设计错误返回模式或多返回值函数中的错误包装时，请参阅 go-error-handling
• 命名约定：命名函数、方法或选择 getter/setter 模式时，请参阅 go-naming
• 函数选项：设计含有 3 个或更多可选参数的构造函数时，请参阅 go-functional-options
• 格式原则：决定行长度、裸返回或签名格式时，请参阅 go-style-core