Gerry’s blog

Minimax in Action

2026-02-28T12:30:00+08:00

MiniMax
在 Claude Code 中使用 MiniMax-M2.1
在 Cursor 中使用 MiniMax-M2.1
- 安装 Cursor
- 在 Cursor 中配置 MiniMax API
在 Cursor 中使用 MiniMax-M2.5
在 OpenClaw 中使用 MiniMax-M2.5
Refer

MiniMax

https://platform.minimaxi.com/subscribe/coding-plan

邀请码：

🎁 MiniMax 跨年福利来袭！邀好友享 Coding Plan 双重好礼，助力开发体验！
好友立享 9折 专属优惠 + Builder 权益，你赢返利 + 社区特权！
👉 立即参与：https://platform.minimaxi.com/subscribe/coding-plan?code=5XvxeGS5Uv&source=link

在 Claude Code 中使用 MiniMax-M2.1

参考：https://platform.minimaxi.com/docs/guides/text-ai-coding-tools

MiniMax-M2.1 & MiniMax-M2.1-lightning 兼容 OpenAI 和 Anthropic 接口协议，适用于代码助手、Agent 工具、AI IDE 等多种场景。

MiniMax 开放平台提供两种计费方案接入文本模型：Coding Plan 以及按量计费。您可按照使用需求选择。调用计费模式取决于您所使用的 API Key，不同类型的 Key 将触发不同的计费方式。

在 .bashrc 添加下面命令：

unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_BASE_URL

安装 Claude Code

可参考 Claude Code 文档进行安装。

获取 API Key

Coding Plan API Key

推荐您订阅 Coding Plan, 为用户的编程提升效率。

访问 Coding Plan 选择最适合的编程套餐
前往账户管理/Conding Plan 页面，查看订阅的 Coding Plan 套餐，并获得 Coding Plan 的 API Key，用于编程工具使用。

开放平台 API Key（按量计费）

访问 MiniMax 开放平台 (国际用户可访问 MiniMax Developer Platform)
点击“创建新的密钥”按钮，输入项目名称以创建新的 API Key
创建成功后，系统将展示 API Key。请务必复制并妥善保存，该密钥只会显示一次，无法再次查看

配置 MiniMax API

安装 cc-switch

cc-switch 是一个便捷的工具，可以快速切换 Claude Code 的 API 配置。

macOS:

brew tap farion1231/ccswitch
brew install --cask cc-switch
brew upgrade --cask cc-switch

Windows:

前往 cc-switch GitHub Releases 页面下载最新版本的安装包。

下载完成后启动 cc-switch 应用：

申请 MiniMax API Key

需要通过绑定银行卡进行实名认证。

https://platform.minimaxi.com/user-center/payment/balance

添加 MiniMax 配置

启动 cc-switch，点击右上角 ”+” ，选择预设的 MiniMax 供应商，并填写用户的 MiniMax API Key。

配置模型名称

将模型名称全部改为 MiniMax-M2.1，完成后点击右下角的 “添加”。

启用配置

回到首页，点击 “启用” 即可开始使用。

启动 Claude Code

配置完成后，进入工作目录，在终端中运行 claude 命令以启动 Claude Code。

信任文件夹

启动后，选择信任此文件夹 (Trust This Folder)，以允许 Claude Code 访问该文件夹中的文件，随后开始在 Claude Code 中使用 MiniMax-M2.1。

执行 `/init` 命令生成 `CLAUDE.md`

Claude Code CLI 的 Bash 脚本包装器

新建一个 claude-minimax 脚本，将从 MiniMax M2 官网获取的接口参数填入。

#!/usr/bin/env bash
# Claude Code CLI wrapper for MiniMax API
# Usage: ./claude-minimax [claude arguments]

CLAUDE_BIN="$HOME/.local/bin/claude"

# Set API credentials for MiniMax
export ANTHROPIC_AUTH_TOKEN="Your Token"
export ANTHROPIC_BASE_URL="https://api.minimaxi.com/anthropic"
export ANTHROPIC_MODEL="MiniMax-M2"
export API_TIMEOUT_MS=3000000

# Optional: Use separate config directory
export CLAUDE_CONFIG_DIR="$HOME/Tools/llm/claude/claude-minimax"

# Execute Claude CLI with all passed arguments
exec "$CLAUDE_BIN" "$@"

功能说明：

设置 MiniMax API 的认证信息
指定使用 MiniMax-M2 模型
配置 API 超时时间为 3000000 毫秒（50分钟）
使用独立的配置目录避免与官方 Claude 配置冲突
将所有参数传递给原版 Claude CLI

完成后，可以测试一下，看看能否正常运行。

$ claude-minimax --version

在 VS Code 使用 Claude Code 生成网页时钟的测试

第一步，新建一个本地目录作为项目目录，比如 ai-clock。然后，在 VS Code 里面打开这个目录 ai-clock，作为工作区。

第二步，打开 VS Code 的菜单”终端/新建终端”，在这个终端窗口里面，输入 claude-minimax。这时，窗口会提示你授予权限，同意后，就会进入主界面，大概就是下面这样。

现在，我们就能在 VS Code 里面使用命令行的 Claude Code 了。这时，你既可以使用 IDE 编写代码，又可以通过命令行使用 AI 模型，兼得两者的优势。

第三步，在 Claude Code 的提示符后面，输入 /init 命令，用来在仓库里面生成一个 CLAUDE.md 文件，记录 AI 对这个仓库操作。

由于示例仓库是空的，所以选择创建一个标准的 CLAUDE.md 模版文件。这个文件的作用是当作上下文，每次查询模型时，都会自动附上这个文件，以便模型了解代码库。

如果在提示框输入反斜杠，Claude Code 就会显示所有可用的命令。通过这些命令，我们就能使用 Claude Code 的强大功能，完成各种 AI 操作了。这一步是 Claude Code 的基础用法，对所有项目都是通用的。

第四步，在提示框输入前面的提示词（下图），让模型生成网页时钟。

Create HTML/CSS of an analog clock showing ${time}. Include numbers (or numerals) if you wish, and have a CSS animated second hand. Make it responsive and use a white background. Return ONLY the HTML/CSS code with no markdown formatting.

翻译成中文就是：”创建一个显示时间 ${time} 的模拟时钟的 HTML/CSS 代码。如果需要，可以包含数字，并添加 CSS 动画秒针。使其具有响应式设计，并使用白色背景。仅返回 HTML/CSS 代码，不要包含任何 Markdown 格式。”

重新执行 /init 命令更新 CLAUDE.md 文件。

在 Cursor 中使用 MiniMax-M2.1

安装 Cursor

通过 Cursor 官网下载并安装 Cursor
打开 Cursor，右上角“设置”按钮，进入设置界面。点击“Sign in”按钮，登录自己的 Cursor 账户

在 Cursor 中配置 MiniMax API

点击左侧栏的 “Models”，进入模型配置页面
展开 “API Keys” 部分，配置 API 信息：
- 勾选 “Override OpenAI Base URL”
- 在下方输入 MiniMax 的调用地址（国内用户使用 https://api.minimaxi.com/v1，国际用户使用 https://api.minimax.io/v1）
在 OpenAI API Key 输入框，配置从 MiniMax 开放平台 (国际用户可访问 MiniMax Developer Platform) 获取的 API Key
点击 “OpenAI API Key” 栏右侧的按钮，在弹出的窗口中点击 “Enable OpenAI API Key” 按钮，完成设置验证
在 Models 板块中，点击 “View All Models” 按钮，并点击 “Add Custom Model” 按钮
输入模型名称 “MiniMax-M2.1” 后，点击 “Add” 按钮
启用刚添加的 “MiniMax-M2.1” 模型
在聊天面板中选择 “MiniMax-M2.1” 模型，开始使用 “MiniMax-M2.1”

在 Cursor 中使用 MiniMax-M2.5

模型名改为 “MiniMax-M2.5”。其余方法参考在 Cursor 中使用 MiniMax-M2.1。

在 OpenClaw 中使用 MiniMax-M2.5

OpenClaw（原 Clawdbot）是一个开源的 AI 助手，完全本地化，可以将各种消息平台与 AI 模型连接起来。它支持 WhatsApp、Telegram、Discord、iMessage 等多种平台，让您可以随时随地与 AI 助手对话。

官方文档：OpenClaw 快速开始指南

配置 MiniMax 模型

推荐使用「一键安装 OAuth 并登录」的方式进行安装。

下面是通过 OAuth 登录的配置方法。

打开配置设置

如果 openclaw 的初始配置引导没有出现模型配置，则可以通过以下命令再次进行 openclaw 配置：

openclaw configure

选择配置选项

Where will the Gateway run? → 选择 Local (this machine)
Select sections to configure → 选择 Model
Model/auth provider → 选择 MiniMax
MiniMax auth method → 选择 MiniMax OAuth
MiniMax endpoint → 选择 CN

登陆授权

登录并授权。

确认模型选择

OAuth 登录完成后，进入模型选择。系统会默认勾选 minimax-portal/MiniMax-M2.1 和 minimax-portal/MiniMax-M2.5，并将 minimax-portal/MiniMax-M2.5 设为默认模型，可直接按回车确认使用。

重启 gateway 使配置生效

执行 openclaw gateway restart 重启 gateway 使得配置生效。

测试对话

输入 openclaw tui，若成功对话则表示配置成功。

Refer

https://platform.minimaxi.com/user-center/payment/coding-plan
通过 AI 编程工具接入

OpenClaw - Personal AI Assistant

2026-01-29T12:00:00+08:00

快速开始
使用示例
- 在 tui 终端对话
- 通过 QQ 客户端对话
- 配置 HTTP 服务
- 实现小游戏
- 生成图片
- 生成音乐
- 生成视频
Skills 最佳实践
- Find Skills 发现其他好用的 Skill
- ClawSec 安全防护
- Self-Improving Agent AI 自我进化
- Tavily Web Search 让 AI 拥有实时信息获取能力
- Multi Search Engine 适合中文信息搜索
- GitHub 代码仓库的自然语言管理
- Proactive Agent 从被动相应到主动服务
- Debug Methodology 问题调试
Skills 数据备份和恢复 (重要)
背景介绍
Quick Start
Moltbot (原 Clawdbot)
What It Does
Works With Everything
Install the CLI (recommended)
Uninstall
Run the onboarding wizard (and install the service)
Auth: where it lives (important)
Start the Gateway
Quick verify (2 min)
Channles
- Imessage
  - Quick setup (beginner)
使用 lighthouse 部署 OpenClaw 全能助手
- 购买 OpenClaw 云服务
- 配置 OpenClaw
- QQ开放平台申请机器人
- Web Search 能力
- 更多用法
常用命令
- 打开终端
- 查看帮助
- 初始化配置
- 配置向导
- 查看配置
- 设置配置
- 启动/停止 Gateway
- 运行时 Gateway
- 查看日志
- 创建新的会话 (清空 token 上下文)
- 系统服务管理
- 发送消息
- 发送媒体文件
- 查看技能列表
- 安装/卸载技能
- 更新技能
- 技能开发
- 查看频道
- 登录频道
- 频道测试
- 频道配置
- 查看会话
- 会话操作
- 查看节点
- 节点操作
- 搜索记忆
- 记忆操作
- 查看 Cron 任务
- 创建 Cron 任务
- Cron 任务操作
- 健康检查
- 系统状态
- 安全检查
- 更新 OpenClaw
Q&A
- MiniMax 接口配置
- 升级 openclaw 版本之后用户之前安装的 skill 失效了
- gateway 异常修复
- Link channel: unknown 错误
Refer

快速开始

官方文档：OpenClaw 快速开始指南

使用示例

在 tui 终端对话

运行 openclaw tui 命令后进行对话。

通过 QQ 客户端对话

创建 QQ Channel 并绑定到 QQbot，然后在 QQ 客户端与 QQbot 进行对话。

注册的 QQbot 信息：

通过 QQbot 查看具备的 Skills 能力：

配置 HTTP 服务

通过 openclaw 配置一个常驻的 HTTP 服务（可以指定数据访问的目录和端口），可方便通过 Web 浏览器查看和下载 openclaw 在云服务器上生成的文件。

# 数据访问目录
/root/.openclaw/workspace/data

# 服务访问端口
8080

在 openclaw 创建完 HTTP 服务后，再在腾讯云控制台通过 AI 助手完成网络访问策略的配置：

通过浏览器测试访问成功：

实现小游戏

生成图片

单独聊天：

QQ群聊天：

生成音乐

http://106.55.160.81:8080/song.mp3

生成视频

http://106.55.160.81:8080/cat_dance_1772715932.mp4

Skills 最佳实践

注意：

skills 中不能记录敏感信息防止泄漏，例如：LLM API Key 的信息，应该将 API Key 的信息配置在服务器独立的配置文件中，例如：/root/.openclaw/workspace/.config/api-keys.json，并只有服务器用户有查看权限。可以通过增加一个 security skill 来保证所需的安全约束。

openclaw 通过 /root/.openclaw/workspace/TOOLS.md 记录可以使用的 skills 技能，增删 skills 目录下的技能描述后，也需要同步更新 TOOLS.md 文件。

通过 ClawHub 安装所需的 skills。

以安装 self-improving-agent 为例，可以使用以下的方法安装：

Install any skill folder in one shot: npx clawhub@latest install your_skill_name
或者在 ClawHub 页面直接下载，https://wry-manatee-359.convex.site/api/v1/download?slug=self-improving-agent。
或者执行 clawdhub install self-improving-agent 命令。
也可以直接告诉 openclaw 让它来安装，例如：通过 https://clawhub.ai/ 安装 self-improving-agent 这个 skill。

Find Skills 发现其他好用的 Skill

Helps users discover and install agent skills when they ask questions like “how do I do X”, “find a skill for X”, “is there a skill that can…”, or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

使用场景：

你想做某件事，但不知道有没有对应的 Skill。例如：想做小红书图片，可以直接让 openclaw 帮你找个适合做小红书图片的技能。然后 openclaw 会根据搜索结果选择一个合适的技能。

实现原理：

接收你的需求描述
向 ClawHub 发起搜索请求
对比不同 Skills 的匹配速度
推荐合适的选择

ClawSec 安全防护

Manage and operate ClawSec Monitor v3.0, a MITM HTTP/HTTPS proxy that logs AI agent traffic, detects exfiltration and injection threats in real time.

Self-Improving Agent AI 自我进化

Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau…

核心思想：

让 Agent 记住自己的错误，学到的东西，用户的纠正，并在后续会话中自动参考。

实现原理：

自动监控。监听命令执行结果，用户反馈
结构化记录。将学习内容记录在 .learnings/ 目录下的日志文件中。每条学习记录包括：ID，时间戳，优先级，摘要，复现步骤，建议修复方案
智能检索。遇到类似问题时，自动查询历史记录

Tavily Web Search 让 AI 拥有实时信息获取能力

AI-optimized web search via Tavily API. Returns concise, relevant results for AI agents.

Multi Search Engine 适合中文信息搜索

Multi search engine integration with 17 engines (8 CN + 9 Global). Supports advanced search operators, time filters, site search, privacy engines, and WolframAlpha knowledge queries. No API keys required.

GitHub 代码仓库的自然语言管理

Interact with GitHub using the gh CLI. Use gh issue, gh pr, gh run, and gh api for issues, PRs, CI runs, and advanced queries.

使用场景：

GitHub Skill 通过集成 GitHub CLI 命令行工具（gh 命令行工具），让你可以用自然语言管理 GitHub 仓库。

例如：

搜索开源项目：搜索 Python 爬虫相关的热门仓库。
管理 Issue：查看某仓库的高优先级 Issue。
代码审查：查看最新的 PR 有没有问题。
自动化报告：生成本周项目进展报告。

实现原理：

理解用户的自然语言指令
转换为对应的 gh 命令
执行并返回结果

Proactive Agent 从被动相应到主动服务

Transform AI agents from task-followers into proactive partners that anticipate needs and continuously improve. Now with WAL Protocol, Working Buffer, Autonomous Crons, and battle-tested patterns. Part of the Hal Stack 🦞

使用场景：

让 openclaw 主动跟踪一个项目的学习进度。例如，每周五自动汇总学习成果，并主动推荐下周的学习计划。这种从“被动执行”到“主动服务”的转变，让 AI 更像一个真正的助理。

实现原理：

心跳机制。每15分钟自动唤醒
任务监控。持续跟踪进行中的任务
自我迭代。优化工作流程

Debug Methodology 问题调试

Systematic debugging and problem-solving methodology. Activate when encountering unexpected errors, service failures, regression bugs, deployment issues, or…

Skills 数据备份和恢复 (重要)

openclaw 保存 Skills 的目录是 ~/.openclaw/workspace/skills/，在保证 Skills 中不存在敏感信息泄漏的情况下，可以将 skills 使用 git 来维护，也可以方便其他场景复用。

背景介绍

命名变化：ClawBot -> MoltBot -> OpenClaw

可以拓展想象：你买了一台新电脑，里面有一个“幽灵实体”，你把键盘、鼠标和网络权限交给它，把它当成一个虚拟同事。你可以直接跟它说话，交代事情。凡是你能在电脑上做的事，这个 Agent 理论上都能替你完成。这就是它真正强大的地方。

个人 AI 助手 Clawdbot 席卷硅谷，国内外社交平台上全是关于它的讨论。不过，项目创始人 Peter Steinberger 在 X 平台上发文表示，他被 Anthropic 强制要求更改名称的成 Moltbot，这并非他本人的决定。这次改名源于商标问题，但在操作过程中不仅搞砸了 GitHub 的账号更名，连 X 平台的原账号名也被加密货币推广者抢注了。最终，他的新账号名定为 @moltbot。使用 Clawdbot 后，网友们纷纷给出了很高的评价。“它是迄今为止最伟大的 AI 应用，相当于你 24 小时全天候专属 AI 员工”。Creator Buddy 创始人兼 CEO Alex Finn 盛赞道，“这就是他们 (Anthropic) 希望 Claude Cowork 呈现的样子”。当前，ClawdBot 项目已经开源：https://github.com/clawdbot/clawdbot。

Alex 展示了给他的 Clawdbot 发信息，让它帮其预订下周六在一家餐厅的座位。当 OpenTable 预订失败时，Clawdbot 利用 ElevenLabs 的技术致电餐厅并完成了预订。

但 Clawdbot 真正让技术圈兴奋的，并不只是“能干活” ，而是其协作方式极其激进：不会写代码的人，也能直接提 PR。原因很简单：它几乎是 100% 用 AI 写出来的，PR 在这里更像是“我遇到了这个问题”，而不是“我写了一段多漂亮的代码”。更有意思的是，这个看似“全开源”的项目，偏偏故意留了一点不开源。创始人 Peter Steinberger 保留了一个名为“soul”的文件只占项目的 0.00001%。他说得很直白：这既是他的”秘密资产”，也是一个刻意留下来的安全靶子。大家真的在试着 hack 它，他就等着看模型到底守不守得住。到目前为止，“soul”还没被偷出来。作为忠实粉丝，Alex 表示这是自 Claude Code 发布以来，自己第一次连续两天没有用它。但是他的 Clawdbot Henry 已经连续 48 小时不停地 Vibe Coding。“我这辈子都没写过这么多代码。Vibe Coding 已死，Vibe Orchestration 已来。”

现在，Alex 想要退掉 Mac Mini，换一台价值 1 万美元的 Mac Studio。“我的 Clawdbot Henry 将控制一台人工智能超级计算机。Henry 将使用 Opus 作为大脑，并使用多个本地模型作为员工集群。” Clawbot 并不是传统意义上只能回答问题的聊天机器人，它本质上是一个持续运行、可以执行任务的个人 AI 智能体。你可以把它安装在自己的设备上，如 Mac、Windows、Linux，它可以长期在线，不停地接收指令、处理任务、记住你的偏好和历史对话，随着时间积累变得更懂你、更有“记忆”。

总的来说，Clawbot 最令人震撼的地方有三点：

它几乎可以完全控制你的电脑。它没有传统意义上的“护栏”，不局限在某几个功能里，而是可以像一个真正坐在电脑前的人一样，操作你电脑上的一切。
它拥有近乎无限的长期记忆。Clawbot 内置了一套非常复杂的记忆系统。说过的话、做过的事，都会不断被记录下来。每次对话结束后，它都会自动总结聊过的内容，并把关键信息提取出来，存进长期记忆中。
它完全通过聊天应用来交互。你平时用哪些聊天工具，Clawbot 就能在哪儿跟你对话，这意味着，只要打开一个聊天软件，就可以通过一条消息把任务交给 Clawbot 去做。现在 Clawbot 支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat 等，还有 BlueBubbles、Matrix、Zalo 以及 Zalo Personal。

不过，如此放开的权限让其几乎没有护栏，这带来很大的安全隐患，现在 GitHub 上有 500 多个安全的问题，这也让部分网友望而却步。对此，很多使用过的用户几乎都表示，不建议一开始就把 Clawbot 装在主力电脑上。“在你还不熟悉它之前，把它放在一个独立环境里是最安全的选择。”

不过大家没有想到，这个 AI 员工首先带火的竟然是 Mac Mini。很多人为了运行 Clawdbot 会专门买一台电脑，而大部分选择了 Mac Mini，原因是它便宜、兼容好、功率低、安静、占地小。谷歌 DeepMind 产品经理 Logan Kilpatrick 都忍不住订了台 Mac Mini。

更有网友晒出自己一口气买了 40 台 Mac mini 来运行 Clawdbot。

但也有网友称可以用一台免费的服务器运行着完全一样的程序，Alex 也称没必要花 600 美元买 Mac mini，有其他便宜得多的方式来运行 Clawbot。买 Mac mini 更多是个人偏好，而不是技术上的必要条件。你完全可以不买任何硬件，只需要一个 VPS。另外，云厂商们动作迅速，有网友发现腾讯云直接推出了 Clawbot 云服务。

随着项目的火爆，其背后的开发者 Peter Steinberger 也备受关注。Peter 在“Open Source Friday”上分享了他一手打造 Clawdbot 的经过，从创建、创始到维护，全由他独自完成。有意思的是，此前甚至有传言称，Peter 可能是一个 bot、Agent，甚至本身就是 AI。而 Peter 的出现也让项目成员和关注者们确认了他是个“真人”。Peter 一度已经退休了，后来又从退休状态里出来开始折腾 AI。从外表来看，Peter 年轻有活力，完全不像已到退休年龄、可领取养老金的人。

Quick Start

Fastest chat: open the Control UI (no channel setup needed). Run moltbot dashboard (PS: 找不到 moltbot 命令可使用 clawdbot 替换，建议将 moltbot 设置为 clawdbot 命令的别名) and chat in the browser, or open http://127.0.0.1:18789/ on the gateway host. Docs: Dashboard and Control UI.

Recommended path: use the CLI onboarding wizard (moltbot onboard). It sets up:

model/auth (OAuth recommended)
gateway settings
channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/…)
pairing defaults (secure DMs)
workspace bootstrap + skills
optional background service

If you want the deeper reference pages, jump to: Wizard, Setup, Pairing, Security.

Moltbot (原 Clawdbot)

Moltbot is a personal AI assistant you run on your own devices. It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat), plus extension channels like BlueBubbles, Matrix, Zalo, and Zalo Personal. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

What It Does

Runs on Your Machine
- Mac, Windows, or Linux. Anthropic, OpenAI, or local models. Private by default - your data stays yours.
Any Chat App
- Talk to it on WhatsApp, Telegram, Discord, Slack, Sigal, or iMessage. Works in DMs and group chats.
Persistent Memory
- Remembers you and becomes uniquely yours. Your preferences, your context, your AI.
Browser Control
- It can browse the web, fill forms, and extract data from any site.
Full System Access
- Read and write files, run shell commands, execute scripts. Full access or sandboxed - your choice.
Skills & Plugins
- Extend with community skills or build your own. It can even write its own.

Works With Everything

See https://www.molt.bot/integrations.

Install the CLI (recommended)

Works on macOS, Windows & Linux. The one-liner installs Node.js and everything else for you.

Runtime: Node ≥22.

#!/bin/bash
# install.sh
curl -fsSL https://molt.bot/install.sh | bash

The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running. Legacy note: clawdbot remains available as a compatibility shim.

具体安装过程如下：

Uninstall

Uninstall the gateway service + local data (CLI remains).

moltbot uninstall
moltbot uninstall --all --yes
moltbot uninstall --dry-run

Run the onboarding wizard (and install the service)

moltbot onboard --install-daemon

What you’ll choose:

Local vs Remote gateway
Auth: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; claude setup-token is also supported.
Providers: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
Daemon: background install (launchd/systemd; WSL2 uses systemd)
- Runtime: Node (recommended; required for WhatsApp/Telegram). Bun is not recommended.
Gateway token: the wizard generates one by default (even on loopback) and stores it in gateway.auth.token.

Wizard doc: Wizard

Auth: where it lives (important)

Recommended Anthropic path: set an API key (wizard can store it for service use). claude setup-token is also supported if you want to reuse Claude Code credentials.
Auth profiles (OAuth + API keys): ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Headless/server tip: do OAuth on a normal machine first, then copy oauth.json to the gateway host.

Start the Gateway

If you installed the service during onboarding, the Gateway should already be running:

moltbot gateway status

Manual run (foreground):

moltbot gateway --port 18789 --verbose

Dashboard (local loopback): http://127.0.0.1:18789/ If a token is configured, paste it into the Control UI settings (stored as connect.params.auth.token).

Quick verify (2 min)

moltbot status
moltbot status --all

moltbot health

moltbot security audit --deep

Tip: moltbot status --all is the best pasteable, read-only debug report. Health probes: moltbot health (or moltbot status --deep) asks the running gateway for a health snapshot.

Channles

Imessage

Status: external CLI integration. Gateway spawns imsg rpc (JSON-RPC over stdio).

Quick setup (beginner)

Ensure Messages is signed in on this Mac.
Install imsg: brew install steipete/tap/imsg
Configure Moltbot with channels.imessage.cliPath and channels.imessage.dbPath.
Start the gateway and approve any macOS prompts (Automation + Full Disk Access).

Minimal config:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db"
    }
  }
}

使用 lighthouse 部署 OpenClaw 全能助手

购买 OpenClaw 云服务

在 https://cloud.tencent.com/act/pro/lighthouse-moltbot 上购买已经集成 OpenClaw 的服务。

配置 OpenClaw

QQ开放平台申请机器人

在 https://q.qq.com/#/ 完成实名注册认证，然后使用注册邮箱登陆。

在管理页面获取到当前机器人的 AppID 和 AppSecret，并且把自己的服务器 IP 填入到白名单中。

登陆终端测试 chatbot 功能是否正常。

添加 QQ 群和自己的 QQ 号，以调用机器人。

在手机端 QQ 中，添加机器人：设置 → 群机器人 → 其他

Web Search 能力

配置 Brave API (收费)

Brave Search 是内置的 web_search 工具，但是收费，可以让 OpenClaw 禁用它，并替换为其他免费的方案。

配置 finnhub (免费)

通过 finnhub 查询股票价格：

配置 tavily (免费)

https://www.tavily.com/

常用命令

参考：https://zhuanlan.zhihu.com/p/2011017776756701009

打开终端

openclaw tui

查看帮助

# 查看所有命令
openclaw --help

# 查看版本号
openclaw --version

# 查看特定命令的帮助
openclaw <command> --help

# 示例：查看 config 命令帮助
openclaw config --help

初始化配置

# 首次安装后初始化配置
openclaw setup

# 交互式引导配置（推荐新手）
openclaw onboard

# 打开控制面板
openclaw dashboard

配置向导

# 打开完整配置向导
openclaw configure

# 打开特定部分配置向导
openclaw configure --section models
openclaw configure --section providers
openclaw configure --section channels

查看配置

# 查看完整配置
openclaw config get

# 查看特定配置项
openclaw config get models.default
openclaw config get providers.mistral.apiKey

# 查看特定部分配置
openclaw config get --section models
openclaw config get --section providers

设置配置

# 设置默认模型
openclaw config set models.default mistral:mixtral-8x7b

# 设置快速模型
openclaw config set models.fast mistral:mistral-7b

# 配置 Mistral API Key
openclaw config set providers.mistral.apiKey YOUR_API_KEY_HERE

# 启用缓存
openclaw config set cache.enabled true
openclaw config set cache.maxSize 5000

启动/停止 Gateway

# 启动 Gateway（默认端口 18789）
openclaw gateway start

# 自定义端口启动
openclaw gateway start --port 19000

# 强制启动（杀死占用进程）
openclaw gateway start --force

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

# 查看运行状态
openclaw gateway status

运行时 Gateway

# 查看健康状态
openclaw health

查看日志

# 查看实时日志
openclaw logs

# 持续监控日志
openclaw logs --follow

创建新的会话 (清空 token 上下文)

通过 /new 指令来新开一个会话

系统服务管理

# 使用 systemd 管理（推荐生产环境）
sudo systemctl start openclaw-gateway
sudo systemctl stop openclaw-gateway
sudo systemctl restart openclaw-gateway
sudo systemctl status openclaw-gateway

# 开机自启动
sudo systemctl enable openclaw-gateway

发送消息

# 发送消息到当前会话
openclaw message send --message "Hello"

# 发送到特定目标（Telegram）
openclaw message send \
  --channel telegram \
  --target @mychat \
  --message "Hello from OpenClaw"

# 发送到特定目标（WhatsApp）
openclaw message send \
  --channel whatsapp \
  --target +8613800138000 \
  --message "您好"

# 发送到 Slack 频道
openclaw message send \
  --channel slack \
  --target C1234567890 \
  --message "@channel 重要通知"

发送媒体文件

# 发送图片
openclaw message send \
  --channel telegram \
  --target @mychat \
  --media /tmp/photo.jpg \
  --caption "这是一张图片"

# 发送音频
openclaw message send \
  --channel whatsapp \
  --target +8613800138000 \
  --media /tmp/voice.mp3

# 发送文档
openclaw message send \
  --channel telegram \
  --target @mychat \
  --media /tmp/report.pdf

查看技能列表

# 查看所有已安装技能
openclaw skills list

# 搜索技能
openclaw skills search weather

# 查看技能详情
openclaw skills show weather

安装/卸载技能

# 安装技能
openclaw skills install weather

# 从指定来源安装
openclaw skills install weather --source github

# 指定版本安装
openclaw skills install weather@1.2.0

# 卸载技能
openclaw skills uninstall weather

更新技能

# 更新所有技能
openclaw skills update

# 更新特定技能
openclaw skills update weather

# 同步技能
openclaw skills sync

技能开发

# 创建新技能
openclaw skills create my-skill

# 验证技能
openclaw skills validate my-skill

# 打包技能
openclaw skills pack my-skill

查看频道

# 查看所有配置的频道
openclaw channels list

# 查看频道状态
openclaw channels status

# 查看特定频道详情
openclaw channels show telegram

登录频道

# Telegram 登录
openclaw channels login --channel telegram

# WhatsApp 登录（会显示 QR 码）
openclaw channels login --channel whatsapp --verbose

# Slack 登录
openclaw channels login --channel slack

# Discord 登录
openclaw channels login --channel discord

频道测试

# 测试频道连接
openclaw channels test --channel telegram

# 发送测试消息
openclaw channels test \
  --channel telegram \
  --target @mychat \
  --message "测试消息"

频道配置

# 配置频道
openclaw channels configure --channel telegram

# 更新频道 Token
openclaw channels update \
  --channel telegram \
  --token NEW_TOKEN

# 启用/禁用频道
openclaw channels enable telegram
openclaw channels disable telegram

查看会话

# 列出所有会话
openclaw sessions

# 列出活跃会话
openclaw sessions --active

# 列出特定频道的会话
openclaw sessions --channel telegram

# 显示最近 10 个会话
openclaw sessions --limit 10

会话操作

# 发送消息到会话
openclaw sessions send \
  --session <session-key> \
  --message "你好"

# 重置会话
openclaw sessions reset <session-key>

# 删除会话
openclaw sessions delete <session-key>

查看节点

# 查看所有配对的节点
openclaw nodes list

# 查看节点状态
openclaw nodes status

# 描述节点详情
openclaw nodes describe <node-id>

节点操作

# 发送通知到节点
openclaw nodes notify \
  --node my-phone \
  --title "提醒" \
  --body "该吃饭了"

# 设置推送优先级
openclaw nodes notify \
  --node my-phone \
  --priority timeSensitive \
  --title "紧急通知" \
  --body "快递到了"

# 查看相册（手机）
openclaw nodes camera-list --node my-phone

# 拍照
openclaw nodes camera-snap \
  --node my-phone \
  --facing back \
  --output /tmp/photo.jpg

搜索记忆

# 搜索记忆
openclaw memory search "OpenClaw 配置"

# 搜索并显示多行上下文
openclaw memory search "配置" --lines 5

# 搜索特定路径的记忆
openclaw memory search "配置" --path MEMORY.md

# 限制结果数量
openclaw memory search "配置" --maxResults 10

记忆操作

# 查看记忆统计
openclaw memory stats

# 清理过期记忆
openclaw memory clean

# 备份记忆
openclaw memory backup --output /tmp/memory-backup.json

查看 Cron 任务

# 列出所有任务
openclaw cron list

# 查看任务运行历史
openclaw cron runs <job-id>

# 查看调度器状态
openclaw cron status

创建 Cron 任务

# 创建定时任务（每天凌晨触发）
openclaw cron add \
  --name "daily-report" \
  --schedule "0 0 * * *" \
  --text "生成每日报告"

# 创建重复任务（每 30 分钟）
openclaw cron add \
  --name "check-notifications" \
  --schedule "*/30 * * * *" \
  --text "检查通知"

# 创建单次任务（特定时间）
openclaw cron add \
  --name "special-task" \
  --schedule "at" \
  --at "2026-03-01T10:00:00" \
  --text "执行特殊任务"

Cron 任务操作

# 立即运行任务
openclaw cron run <job-id>

# 更新任务
openclaw cron update <job-id> --schedule "0 6 * * *"

# 删除任务
openclaw cron remove <job-id>

# 发送唤醒事件
openclaw cron wake --text "检查新消息"

健康检查

# 运行健康检查
openclaw doctor

# 快速修复常见问题
openclaw doctor --fix

系统状态

# 查看频道健康状态
openclaw status

# 查看系统事件
openclaw system events

# 查看心跳状态
openclaw system heartbeat

安全检查

# 运行安全检查
openclaw security audit

# 检查权限配置
openclaw security check-permissions

# 检查 API Key 有效性
openclaw security verify-keys

更新 OpenClaw

# 查看更新
openclaw update --dry-run

# 执行更新
openclaw update

# 更新到特定版本
openclaw update --tag 2026.2.22

# 更新到 Beta 版
openclaw update --channel beta

# 安全更新流程
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup \
  && openclaw update --dry-run \
  && openclaw update \
  && openclaw gateway restart

Q&A

MiniMax 接口配置

由于 Kimi、MiniMax、GLM 分了国际版和国内版，Clawdbot 默认集成的是国际版的接口地址，因此如果在配置模型时需要使用这三家的模型，则需要登录国际版控制台申请 API Key：

Kimi：https://platform.moonshot.ai/
MiniMax：https://platform.minimax.io/
GLM：https://z.ai/manage-apikey/apikey-list

升级 openclaw 版本之后用户之前安装的 skill 失效了

问题现象：openclaw 升级到 2026.3.2 版本后，出现 openclaw 访问权限错误，工作区下 Skills (/root/.openclaw/workspace/skills/) 都会提示工具不可用。

# openclaw --version
2026.3.2

问题原因：openclaw 的版本权限收拢了，之前没有这个限制。查看 cat /root/.openclaw/openclaw.json | grep profile，新版本默认为 messaging，需要将其改为 full。

gateway 异常修复

问题现象：使用 openclaw onboard 重新安装 gateway 出现异常导致 gateway 被删除且安装失败。

使用 openclaw gateway install --force 重新安装也会提示失败。

参考：https://www.answeroverflow.com/m/1478602967488790682?focus=1478602967488790682 找到了解决方法：

systemctl --user is-enabled openclaw-gateway.service → not-found means the systemd user unit was never installed
Let Doctor rewrite the service to a sane modern config (incl. PATH): openclaw doctor --repair
Restart: openclaw gateway restart
Verify: systemctl --user status openclaw-gateway.service --no-pager && openclaw gateway status
Log: journalctl --user -u openclaw-gateway.service -n 200 --no-pager

Link channel: unknown 错误

问题现象：使用 tui channel 没有实时返回结果信息，而显示 gateway connected | idle 状态。

Refer

https://www.molt.bot/
https://docs.molt.bot/
https://github.com/moltbot/moltbot
https://docs.molt.bot/getting-started
https://docs.molt.bot/start/getting-started
https://docs.molt.bot/help/troubleshooting
https://docs.molt.bot/help/faq
被 Anthropic 强制要求改名！Clawdbot 创始人一人开发、100% AI 写代码
云上Moltbot（原Clawdbot）最全实践指南合辑
云上Moltbot（原Clawdbot）接入企业微信完全指南
云上Moltbot（原Clawdbot）接入QQ完全指南

School English Notes

2026-01-17T12:30:00+08:00

单词记忆方法
英语五年级上册单词
- Unit 1
- Unit 2
- Unit 3
- Unit 4
- Unit 5
- Unit 6
- Unit 7
- Unit 8
- Unit 9
- Unit 10
- Unit 11
- Unit 12
英语六年级上册单词
- Unit 1

教材：上海教育出版社

单词记忆方法

1. 分类记忆法（按主题分组）

将单词按主题分类，同类单词一起记忆效果更好：

Unit 1: 职业类（pilot, cook, singer, lifeguard）
Unit 2: 交通类（by bus, by bike, station, underground）
Unit 3: 序数词（first, second, third…）
Unit 4: 频率副词（usually, often, sometimes, always, never）
Unit 5: 日常交流类（clever, same, class, ask, answer, each other）
Unit 6: 房间类（living room, bedroom, kitchen, bathroom）
Unit 7: 度假类（beach, sunshine, shell, sea）
Unit 8: 远足探险类（outing, map, hill, find, diamond, lake）
Unit 9: 方向类（left, right, straight, turn）
Unit 10: 副词类（gently, softly, strongly, slowly, quickly）
Unit 11: 生活自然类（tap, use, vegetable, farmer, mountain, tree）
Unit 12: 安全类（fire, burn, safety, careful）

2. 艾宾浩斯遗忘曲线复习法

根据遗忘曲线规律，科学安排复习时间：

第1天：学习 Unit 1-4
第2天：复习 Unit 1-4，学习 Unit 5-8
第3天：复习 Unit 1-8，学习 Unit 9-12
第4天：全面复习，重点攻克薄弱单元

3. 联想记忆法

通过联想帮助记忆：

词根联想：underground = under（下）+ ground（地面）= 地铁
音形联想：journey 听起来像”就你”，想象”旅程就你一个人”
场景联想：living room（客厅）→ 生活的地方

4. 卡片记忆法

制作单词卡片：正面英文，背面中文
快速过一遍，把会的放一边，不会的反复看
利用碎片时间（上学路上、课间）复习

5. 口诀记忆法

序数词规律：first, second, third 特殊记，fourth 开始加 -th
频率副词排序：always > usually > often > sometimes > never

6. 重点攻克难点单词

长单词：favourite, interesting, thirteenth, twenty-first
易混淆：bring vs thing, quiet (/ˈkwaɪət/) vs quite (/kwaɪt/)
短语：(be) good at, have a good time, each other

7. 实战练习建议

每天默写1-2个单元
用单词造句，加深理解
找同学互相听写，互相纠正

8. 考前冲刺（最后1-2天）

快速浏览所有单词，标记不熟悉的
重点复习标记的单词
做模拟测试，查漏补缺

英语五年级上册单词

Unit 1

Title: My future Category: 职业类

future /ˈfjuːtʃə/ 将来；未来
- 例句：I want to be a teacher in the future. (我将来想成为一名老师。)
want /wɒnt/ 想要
- 例句：I want an apple. (我想要一个苹果。)
pilot /ˈpaɪlət/ 飞行员
- 例句：My uncle is a pilot. (我叔叔是一名飞行员。)
- 记忆：pilot 开飞机，pilot 很厉害！
teach /tiːtʃ/ 教(课)
- 例句：My teacher teaches English. (我的老师教英语。)
cook /kʊk/ 厨师；烹饪
- 例句：My mother is a good cook. (我妈妈是个好厨师。)
taxi driver /ˈtæksi ˈdraɪvə/ 出租车司机
- 例句：The taxi driver is very friendly. (出租车司机很友好。)
- 记忆：taxi（出租车）+ driver（司机）= taxi driver
job /dʒɒb/ 工作；职业
- 例句：What’s your job? (你的工作是什么？)
singer /ˈsɪŋə/ 歌手
- 例句：She wants to be a singer. (她想成为一名歌手。)
- 记忆：sing（唱歌）+ er（人）= singer（歌手）
fall /fɔːl/ 掉落；落下
- 例句：The apple falls from the tree. (苹果从树上掉下来。)
lifeguard /ˈlaɪfɡɑːd/ 救生员
- 例句：The lifeguard helps people at the beach. (救生员在海滩帮助人们。)
- 记忆：life（生命）+ guard（守卫）= lifeguard（救生员）
save /seɪv/ 救；救助；节约
- 例句：The lifeguard saves people. (救生员救人。)
become /bɪˈkʌm/ 变成；变得
- 例句：I want to become a doctor. (我想成为一名医生。)
(be) good at /biː ɡʊd æt/ 擅长
- 例句：I am good at English. (我擅长英语。)

Unit 2

Title: Going to school Category: 交通类

by /baɪ/ (表示方式)；靠近
- 例句：I go to school by bus. (我乘公共汽车去学校。)
walk /wɔːk/ 走；步行
- 例句：I walk to school every day. (我每天步行去学校。)
Ms /mɪz/ 女士
- 例句：Ms Wang is my teacher. (王女士是我的老师。)
journey /ˈdʒɜːni/ 旅程；旅行
- 例句：It’s a long journey. (这是一次长途旅行。)
primary school /ˈpraɪməri skuːl/ 小学
- 例句：I study at a primary school. (我在小学学习。)
- 记忆：primary（初级的）+ school（学校）= primary school（小学）
underground /ˈʌndəɡraʊnd/ 地铁
- 例句：I take the underground to school. (我乘地铁去学校。)
- 记忆：under（下）+ ground（地面）= underground（地铁）
station /ˈsteɪʃən/ 车站
- 例句：The train station is big. (火车站很大。)
take /teɪk/ 乘坐(交通工具)；带领
- 例句：I take the bus to school. (我乘公共汽车去学校。)
after /ˈɑːftə/ 在……后
- 例句：I do homework after school. (放学后我做作业。)
hour /ˈaʊə/ 小时
- 例句：I sleep for eight hours. (我睡八小时。)
bus stop /bʌs stɒp/ 公共汽车站
- 例句：I wait at the bus stop. (我在公共汽车站等车。)
- 记忆：bus（公共汽车）+ stop（站）= bus stop
by bus /baɪ bʌs/ 乘公共汽车
- 例句：I go home by bus. (我乘公共汽车回家。)
far from /fɑː frɒm/ 离……远
- 例句：My school is far from my home. (我的学校离我家很远。)
on foot /ɒn fʊt/ 步行
- 例句：I go to the park on foot. (我步行去公园。)
by bike /baɪ baɪk/ 骑自行车
- 例句：I go to school by bike. (我骑自行车去学校。)
by car /baɪ kɑː/ 乘小汽车
- 例句：My father goes to work by car. (我爸爸开车去上班。)
get off /ɡet ɒf/ 下车
- 例句：I get off the bus at the school. (我在学校下车。)

Unit 3

Title: My birthday Category: 序数词

party /ˈpɑːti/ 聚会
- 例句：I go to a birthday party. (我去参加生日聚会。)
when /wen/ 什么时候
- 例句：When do you go to school? (你什么时候去学校？)
begin /bɪˈɡɪn/ 开始
- 例句：The class begins at eight. (课在八点开始。)
bring /brɪŋ/ 带来
- 例句：Please bring your book. (请带上你的书。)
- 记忆：bring（带来）和 thing（东西）容易混淆，bring 是动作
thing /θɪŋ/ 东西；事物
- 例句：This is a nice thing. (这是一个好东西。)
- 记忆：thing（东西）和 bring（带来）容易混淆，thing 是名词
favourite /ˈfeɪvərɪt/ 最喜欢的
- 例句：Apple is my favourite fruit. (苹果是我最喜欢的水果。)
interesting /ˈɪntrəstɪŋ/ 有趣的
- 例句：This book is very interesting. (这本书很有趣。)
hat /hæt/ 帽子
- 例句：I wear a red hat. (我戴一顶红帽子。)
have fun /hæv fʌn/ 尽情玩
- 例句：We have fun at the party. (我们在聚会上玩得很开心。)
first /fɜːst/ 第一
- 例句：I am the first in the race. (我在比赛中得了第一。)
second /ˈsekənd/ 第二
- 例句：He is the second student. (他是第二个学生。)
third /θɜːd/ 第三
- 例句：Today is the third day. (今天是第三天。)
fourth /fɔːθ/ 第四
- 例句：Today is the fourth day. (今天是第四天。)
- 记忆：four（四）+ th = fourth（第四）
fifth /fɪfθ/ 第五
- 例句：This is the fifth book. (这是第五本书。)
- 记忆：five（五）→ fifth（第五），注意 ve 变 f 再加 th
sixth /sɪksθ/ 第六
- 例句：I am in the sixth grade. (我在六年级。)
- 记忆：six（六）+ th = sixth（第六）
seventh /ˈsevənθ/ 第七
- 例句：This is the seventh month. (这是第七个月。)
- 记忆：seven（七）+ th = seventh（第七）
eighth /eɪtθ/ 第八
- 例句：Today is the eighth day. (今天是第八天。)
- 记忆：eight（八）+ th = eighth（第八），注意只有一个 t
ninth /naɪnθ/ 第九
- 例句：This is the ninth lesson. (这是第九课。)
- 记忆：nine（九）→ ninth（第九），去掉 e 加 th
tenth /tenθ/ 第十
- 例句：This is the tenth question. (这是第十个问题。)
- 记忆：ten（十）+ th = tenth（第十）
eleventh /ɪˈlevənθ/ 第十一
- 例句：Today is the eleventh day. (今天是第十一天。)
- 记忆：eleven（十一）+ th = eleventh（第十一）
twelfth /twelfθ/ 第十二
- 例句：This is the twelfth month. (这是第十二个月。)
- 记忆：twelve（十二）→ twelfth（第十二），注意 ve 变 f 再加 th
thirteenth /ˌθɜːˈtiːnθ/ 第十三
- 例句：Today is the thirteenth day. (今天是第十三天。)
- 记忆：thirteen（十三）+ th = thirteenth（第十三）
fourteenth /ˌfɔːˈtiːnθ/ 第十四
- 例句：This is the fourteenth lesson. (这是第十四课。)
- 记忆：fourteen（十四）+ th = fourteenth（第十四）
fifteenth /ˌfɪfˈtiːnθ/ 第十五
- 例句：Today is the fifteenth day. (今天是第十五天。)
- 记忆：fifteen（十五）+ th = fifteenth（第十五）
sixteenth /ˌsɪkˈstiːnθ/ 第十六
- 例句：This is the sixteenth question. (这是第十六个问题。)
- 记忆：sixteen（十六）+ th = sixteenth（第十六）
seventeenth /ˌsevənˈtiːnθ/ 第十七
- 例句：Today is the seventeenth day. (今天是第十七天。)
- 记忆：seventeen（十七）+ th = seventeenth（第十七）
eighteenth /ˌeɪˈtiːnθ/ 第十八
- 例句：This is the eighteenth lesson. (这是第十八课。)
- 记忆：eighteen（十八）+ th = eighteenth（第十八）
nineteenth /ˌnaɪnˈtiːnθ/ 第十九
- 例句：Today is the nineteenth day. (今天是第十九天。)
- 记忆：nineteen（十九）→ nineteenth（第十九），去掉 e 加 th
twentieth /ˈtwentiəθ/ 第二十
- 例句：This is the twentieth question. (这是第二十个问题。)
- 记忆：twenty（二十）→ twentieth（第二十），y 变 ie 加 th
twenty-first /ˌtwenti ˈfɜːst/ 第二十一
- 例句：Today is the twenty-first day. (今天是第二十一天。)
- 记忆：twenty（二十）+ first（第一）= twenty-first
twenty-second /ˌtwenti ˈsekənd/ 第二十二
- 例句：This is the twenty-second lesson. (这是第二十二课。)
- 记忆：twenty（二十）+ second（第二）= twenty-second
twenty-third /ˌtwenti ˈθɜːd/ 第二十三
- 例句：Today is the twenty-third day. (今天是第二十三天。)
- 记忆：twenty（二十）+ third（第三）= twenty-third
twenty-fourth /ˌtwenti ˈfɔːθ/ 第二十四
- 例句：This is the twenty-fourth question. (这是第二十四个问题。)
- 记忆：twenty（二十）+ fourth（第四）= twenty-fourth
twenty-fifth /ˌtwenti ˈfɪfθ/ 第二十五
- 例句：Today is the twenty-fifth day. (今天是第二十五天。)
- 记忆：twenty（二十）+ fifth（第五）= twenty-fifth
twenty-sixth /ˌtwenti ˈsɪksθ/ 第二十六
- 例句：This is the twenty-sixth lesson. (这是第二十六课。)
- 记忆：twenty（二十）+ sixth（第六）= twenty-sixth
twenty-seventh /ˌtwenti ˈsevənθ/ 第二十七
- 例句：Today is the twenty-seventh day. (今天是第二十七天。)
- 记忆：twenty（二十）+ seventh（第七）= twenty-seventh
twenty-eighth /ˌtwenti ˈeɪtθ/ 第二十八
- 例句：This is the twenty-eighth question. (这是第二十八个问题。)
- 记忆：twenty（二十）+ eighth（第八）= twenty-eighth
twenty-ninth /ˌtwenti ˈnaɪnθ/ 第二十九
- 例句：Today is the twenty-ninth day. (今天是第二十九天。)
- 记忆：twenty（二十）+ ninth（第九）= twenty-ninth
thirtieth /ˈθɜːtiəθ/ 第三十
- 例句：This is the thirtieth question. (这是第三十个问题。)
- 记忆：thirty（三十）→ thirtieth（第三十），y 变 ie 加 th
thirty-first /ˌθɜːti ˈfɜːst/ 第三十一
- 例句：Today is the thirty-first day. (今天是第三十一天。)
- 记忆：thirty（三十）+ first（第一）= thirty-first

Unit 4

Title: Grandparents Category: 频率副词

usually /ˈjuːʒuəli/ 通常
- 例句：I usually go to school at seven. (我通常七点去学校。)
often /ˈɒfən/ 经常
- 例句：I often read books. (我经常读书。)
visit /ˈvɪzɪt/ 看望；拜访；参观
- 例句：I visit my grandparents. (我看望我的祖父母。)
sometimes /ˈsʌmtaɪmz/ 有时
- 例句：Sometimes I play football. (有时我踢足球。)
always /ˈɔːlweɪz/ 总是；一直
- 例句：I always do my homework. (我总是做作业。)
never /ˈnevə/ 从不
- 例句：I never go to bed late. (我从不晚睡。)
play sport /pleɪ spɔːt/ 做运动
- 例句：I play sport every day. (我每天做运动。)
go shopping /ɡəʊ ˈʃɒpɪŋ/ 去购物
- 例句：My mother goes shopping on Sunday. (我妈妈星期天去购物。)

Unit 5

Title: Friends Category: 日常交流类

clever /ˈklevə/ 聪明的
- 例句：Tom is a clever boy. (汤姆是个聪明的男孩。)
same /seɪm/ 相同的
- 例句：We are in the same class. (我们在同一个班级。)
class /klɑːs/ 班；班级
- 例句：I am in Class One. (我在一班。)
both /bəʊθ/ (两个)都
- 例句：Both of us like English. (我们两个都喜欢英语。)
cross /krɒs/ 穿越；越过
- 例句：Don’t cross the road here. (不要在这里过马路。)
carry /ˈkæri/ 背；提；拿
- 例句：I carry a heavy bag. (我背着一个重包。)
heavy /ˈhevi/ 重的；沉的
- 例句：This box is very heavy. (这个箱子很重。)
different /ˈdɪfərənt/ 不同的
- 例句：We are different. (我们是不同的。)
bored /bɔːd/ 无聊的
- 例句：I feel bored. (我感到无聊。)
word /wɜːd/ 单词
- 例句：This is a new word. (这是一个新单词。)
easy /ˈiːzi/ 容易的
- 例句：This question is easy. (这个问题很容易。)
say /seɪ/ 说
- 例句：What do you say? (你说什么？)
then /ðen/ 然后；那么
- 例句：First I read, then I write. (我先读，然后写。)
ask /ɑːsk/ 问
- 例句：I ask the teacher a question. (我问老师一个问题。)
answer /ˈɑːnsə/ 回答
- 例句：Please answer my question. (请回答我的问题。)
soon /suːn/ 很快；不久
- 例句：I will come back soon. (我很快回来。)
each other /iːtʃ ˈʌðə/ 互相
- 例句：We help each other. (我们互相帮助。)
make phone calls /meɪk fəʊn kɔːlz/ 打电话
- 例句：I make phone calls to my friends. (我给朋友打电话。)

Unit 6

Title: Family life Category: 房间类

life /laɪf/ 生活
- 例句：Life is beautiful. (生活是美好的。)
living room /ˈlɪvɪŋ ruːm/ 客厅
- 例句：We watch TV in the living room. (我们在客厅看电视。)
- 记忆：living（生活）+ room（房间）= living room（客厅）
bedroom /ˈbedruːm/ 卧室
- 例句：I sleep in my bedroom. (我在卧室睡觉。)
- 记忆：bed（床）+ room（房间）= bedroom（卧室）
model plane /ˈmɒdəl pleɪn/ 飞机模型
- 例句：I have a model plane. (我有一个飞机模型。)
kitchen /ˈkɪtʃɪn/ 厨房
- 例句：My mother cooks in the kitchen. (我妈妈在厨房做饭。)
bathroom /ˈbɑːθruːm/ 浴室；卫生间
- 例句：I brush my teeth in the bathroom. (我在浴室刷牙。)
- 记忆：bath（洗澡）+ room（房间）= bathroom（浴室）
their /ðeə/ 他们的；她们的；它们的
- 例句：This is their book. (这是他们的书。)
light /laɪt/ 灯；光
- 例句：Turn on the light, please. (请开灯。)
watch /wɒtʃ/ 观看；观察
- 例句：I watch TV in the evening. (我晚上看电视。)
TV /ˌtiː ˈviː/ 电视；电视机
- 例句：I like watching TV. (我喜欢看电视。)
before /bɪˈfɔː/ 在……以前
- 例句：I do homework before dinner. (我在晚饭前做作业。)
bedtime /ˈbedtaɪm/ 就寝时间
- 例句：My bedtime is nine o’clock. (我的就寝时间是九点。)
- 记忆：bed（床）+ time（时间）= bedtime（就寝时间）
do … homework /duː ˈhəʊmwɜːk/ 做家庭作业
- 例句：I do my homework every day. (我每天做家庭作业。)
turn off /tɜːn ɒf/ 关掉
- 例句：Turn off the light, please. (请关灯。)
watch TV /wɒtʃ ˌtiː ˈviː/ 看电视
- 例句：I watch TV after dinner. (我晚饭后看电视。)
tell a story /tel ə ˈstɔːri/ 讲故事
- 例句：My mother tells me a story. (我妈妈给我讲故事。)

Unit 7

Title: At the beach Category: 度假类

beach /biːtʃ/ 海滩
- 例句：We play on the beach. (我们在海滩上玩。)
enjoy /ɪnˈdʒɔɪ/ 享受…的乐趣
- 例句：I enjoy reading books. (我喜欢读书。)
sunshine /ˈsʌnʃaɪn/ 阳光
- 例句：We enjoy the sunshine on the beach. (我们在海滩享受阳光。)
- 记忆：sun（太阳）+ shine（照耀）= sunshine（阳光）
collect /kəˈlekt/ 收集
- 例句：I collect shells. (我收集贝壳。)
shell /ʃel/ 贝壳
- 例句：I find a beautiful shell. (我找到一个漂亮的贝壳。)
sea /siː/ 海
- 例句：The sea is blue. (大海是蓝色的。)
letter /ˈletə/ 信
- 例句：I write a letter to my friend. (我给我的朋友写信。)
put /pʊt/ 放；安置
- 例句：Put the book on the desk. (把书放在桌子上。)
know /nəʊ/ 知道
- 例句：I know the answer. (我知道答案。)
year /jɪə/ 年岁；年
- 例句：I am ten years old. (我十岁了。)
on holiday /ɒn ˈhɒlədi/ 度假
- 例句：We go to the beach on holiday. (我们度假时去海滩。)
have a good time /hæv ə ɡʊd taɪm/ 玩得高兴
- 例句：We have a good time at the beach. (我们在海滩玩得很开心。)

Unit 8

Title: An outing Category: 远足探险类

outing /ˈaʊtɪŋ/ 远足
- 例句：We go on an outing. (我们去远足。)
map /mæp/ 地图
- 例句：I look at the map. (我看地图。)
hill /hɪl/ 小山
- 例句：There is a hill over there. (那边有一座小山。)
find /faɪnd/ 发现；找到
- 例句：I find a key. (我找到一把钥匙。)
diamond /ˈdaɪəmənd/ 钻石
- 例句：The diamond is very beautiful. (钻石很漂亮。)
another /əˈnʌðə/ 另一个
- 例句：I want another apple. (我想要另一个苹果。)
lake /leɪk/ 湖
- 例句：The lake is very big. (这个湖很大。)
funny /ˈfʌni/ 滑稽的；好笑的
- 例句：This story is very funny. (这个故事很有趣。)
hole /həʊl/ 洞
- 例句：There is a hole in the wall. (墙上有一个洞。)
key /kiː/ 钥匙
- 例句：This is the key to the door. (这是门的钥匙。)
think /θɪŋk/ 想
- 例句：I think it’s good. (我认为这很好。)
at the top of /æt ðə tɒp ɒv/ 在……顶部
- 例句：The flag is at the top of the hill. (旗子在山顶。)
get through /ɡet θruː/ 通过
- 例句：We get through the hole. (我们通过这个洞。)

Unit 9

Title: Around the city Category: 方向类

post office /pəʊst ˈɒfɪs/ 邮局
- 例句：I send a letter at the post office. (我在邮局寄信。)
- 记忆：post（邮政）+ office（办公室）= post office（邮局）
quite /kwaɪt/ 相当；十分
- 例句：It’s quite good. (这相当好。)
- 记忆：quite（相当）和 quiet（安静的）容易混淆，quite 是副词
along /əˈlɒŋ/ 沿着；顺着
- 例句：Walk along this road. (沿着这条路走。)
turn /tɜːn/ 转向；转弯
- 例句：Turn left at the corner. (在拐角处向左转。)
left /left/ 左边
- 例句：The book is on the left. (书在左边。)
straight /streɪt/ 笔直地
- 例句：Go straight ahead. (一直往前走。)
right /raɪt/ 右边；正确的
- 例句：Turn right here. (在这里向右转。)
between /bɪˈtwiːn/ 在…中间
- 例句：The book is between two pens. (书在两支笔中间。)
flower shop /ˈflaʊə ʃɒp/ 花店
- 例句：My mother buys flowers at the flower shop. (我妈妈在花店买花。)
- 记忆：flower（花）+ shop（商店）= flower shop（花店）
hospital /ˈhɒspɪtəl/ 医院
- 例句：My father works in a hospital. (我爸爸在医院工作。)
toy shop /tɔɪ ʃɒp/ 玩具店
- 例句：I buy toys at the toy shop. (我在玩具店买玩具。)
- 记忆：toy（玩具）+ shop（商店）= toy shop（玩具店）
road /rəʊd/ 路；马路
- 例句：This road is very long. (这条路很长。)
get to /ɡet tuː/ 到达
- 例句：How do I get to the school? (我怎么到学校？)

Unit 10

Title: Wind Category: 副词类

blow /bləʊ/ 刮；吹
- 例句：The wind blows gently. (风轻轻地吹。)
gently /ˈdʒentli/ 和缓地；温柔地
- 例句：The wind blows gently. (风轻轻地吹。)
softly /ˈsɒftli/ 轻柔地
- 例句：She speaks softly. (她轻声说话。)
strongly /ˈstrɒŋli/ 强劲地
- 例句：The wind blows strongly. (风强劲地吹。)
happily /ˈhæpɪli/ 快乐地
- 例句：We play happily. (我们快乐地玩。)
windmill /ˈwɪndmɪl/ 风车
- 例句：The windmill turns in the wind. (风车在风中转动。)
- 记忆：wind（风）+ mill（磨坊）= windmill（风车）
move /muːv/ (使)改变位置；移动
- 例句：Don’t move! (别动！)
slowly /ˈsləʊli/ 缓慢地
- 例句：The old man walks slowly. (老人慢慢地走。)
quickly /ˈkwɪkli/ 快地；迅速地
- 例句：I run quickly. (我跑得很快。)
sound /saʊnd/ 声乐；听起来好像
- 例句：It sounds good. (听起来不错。)
wind-bell /ˈwɪnd bel/ 风铃
- 例句：The wind-bell makes a nice sound. (风铃发出好听的声音。)
- 记忆：wind（风）+ bell（铃）= wind-bell（风铃）
cut /kʌt/ 剪；砍；切
- 例句：I cut the paper. (我剪纸。)
paper /ˈpeɪpə/ 纸；纸张
- 例句：I write on paper. (我在纸上写字。)
quiet /ˈkwaɪət/ 轻声的；安静的
- 例句：Please be quiet. (请安静。)
- 记忆：quiet（安静的）和 quite（相当）容易混淆，quiet 是形容词

Unit 11

Title: Water Category: 生活自然类

tap /tæp/ 水龙头
- 例句：Turn on the tap. (打开水龙头。)
use /juːz/ 使用
- 例句：I use water to wash. (我用水来洗。)
vegetable /ˈvedʒtəbəl/ 蔬菜
- 例句：I like eating vegetables. (我喜欢吃蔬菜。)
clothes /kləʊðz/ 衣服；服装
- 例句：I wash my clothes. (我洗衣服。)
farmer /ˈfɑːmə/ 农民
- 例句：The farmer grows vegetables. (农民种蔬菜。)
- 记忆：farm（农场）+ er（人）= farmer（农民）
useful /ˈjuːsfəl/ 有用的
- 例句：This book is very useful. (这本书很有用。)
- 记忆：use（使用）+ ful（充满的）= useful（有用的）
drop /drɒp/ 滴；水珠
- 例句：A drop of water falls. (一滴水落下。)
up /ʌp/ 向上；在上面
- 例句：Look up! (向上看！)
shine /ʃaɪn/ 照耀
- 例句：The sun shines. (太阳照耀。)
over /ˈəʊvə/ 在……上方
- 例句：The bridge is over the river. (桥在河上方。)
mountain /ˈmaʊntɪn/ 山；山脉
- 例句：The mountain is very high. (这座山很高。)
tree /triː/ 树
- 例句：There is a big tree. (有一棵大树。)
ground /ɡraʊnd/ 地面
- 例句：The apple falls to the ground. (苹果掉到地上。)
inside /ˌɪnˈsaɪd/ 在……里面
- 例句：The cat is inside the box. (猫在盒子里。)
grow crops /ɡrəʊ krɒps/ 种庄稼
- 例句：Farmers grow crops. (农民种庄稼。)
put out fires /pʊt aʊt ˈfaɪəz/ 灭火
- 例句：Firefighters put out fires. (消防员灭火。)

Unit 12

Title: Fire Category: 安全类

fire /ˈfaɪə/ 火；火灾
- 例句：Fire is dangerous. (火是危险的。)
burn /bɜːn/ 燃烧；烧
- 例句：Don’t let the paper burn. (不要让纸烧起来。)
hurt /hɜːt/ (使)受伤
- 例句：The fire can hurt you. (火会伤害你。)
must /mʌst/ 必须
- 例句：You must be careful. (你必须小心。)
careful /ˈkeəfəl/ 小心的
- 例句：Be careful with fire. (小心火。)
safety /ˈseɪfti/ 安全
- 例句：Safety is important. (安全很重要。)
smoke /sməʊk/ 吸烟
- 例句：Don’t smoke here. (不要在这里吸烟。)
match /mætʃ/ 火柴
- 例句：Don’t play with matches. (不要玩火柴。)
heat /hiːt/ 热；高温
- 例句：The heat is very strong. (热量很强。)
hate /heɪt/ 讨厌
- 例句：I hate fire. (我讨厌火。)
burn down /bɜːn daʊn/ 烧毁
- 例句：The fire can burn down the house. (火会烧毁房子。)
(be) careful with /biː ˈkeəfəl wɪð/ 当心……
- 例句：Be careful with fire. (小心火。)
not … at all /nɒt æt ɔːl/ 一点也不
- 例句：I don’t like it at all. (我一点也不喜欢它。)

英语六年级上册单词

Unit 1

Title: Growing up Category: 成长变化类

month /mʌnθ/ 一个月的时间；月份
- 例句：There are twelve months in a year. (一年有十二个月。)
cute /kjuːt/ 可爱的
- 例句：The baby is very cute. (这个婴儿很可爱。)
pretty /ˈprɪti/ 漂亮的
- 例句：She is a pretty girl. (她是个漂亮的女孩。)
handsome /ˈhænsəm/ 英俊的；帅气的
- 例句：He is a handsome boy. (他是个帅气的男孩。)
turtle /ˈtɜːtəl/ 乌龟
- 例句：I have a pet turtle. (我有一只宠物乌龟。)
catch /kætʃ/ 逮住；捕捉
- 例句：I catch a fly. (我捉住了一只苍蝇。)
fly /flaɪ/ 苍蝇
- 例句：There is a fly on the table. (桌子上有一只苍蝇。)
grow up /ɡrəʊ ʌp/ 长大；成长
- 例句：I want to grow up quickly. (我想快点长大。)
junior high school /ˈdʒuːniə haɪ skuːl/ 初级中学
- 例句：I will go to junior high school next year. (我明年将上初级中学。)
- 记忆：junior（初级的）+ high school（中学）= junior high school（初级中学）
(be) born /biː bɔːn/ 出生
- 例句：I was born in 2010. (我出生于2010年。)

Protolint in Action

2025-12-30T08:00:00+08:00

基本用法
Installation
Usage
Version Control Integration
Editor Integration
Call from Go code
Rules
Examples
Creating your custom rules
Reporters
Configure
- Disable rules in a Protocol Buffer file
- Config file
Exit codes
Refer

protolint is the pluggable linting/fixing utility for Protocol Buffer files (proto2+proto3):

Runs fast because this works without compiler.
Easy to follow the official style guide. The rules and the style guide correspond to each other exactly.
- Fixer automatically fixes all the possible official style guide violations.
Allows to disable rules with a comment in a Protocol Buffer file.
- It is useful for projects which must keep API compatibility while enforce the style guide as much as possible.
- Some rules can be automatically disabled by inserting comments to the spotted violations.
Loads plugins to contain your custom lint rules.
Undergone testing for all rules.
Many integration supports.
- protoc plugin
- Editor integration
- GitHub Action
- CI Integration

基本用法

查看所有规则

protolint list

常见规则：

根据 protolint list 的输出，常用规则包括：

MAX_LINE_LENGTH: 行长度限制（默认 80）
IMPORTS_SORTED: 导入排序
INDENT: 缩进风格
SERVICE_NAMES_UPPER_CAMEL_CASE: 服务名大驼峰
RPC_NAMES_UPPER_CAMEL_CASE: RPC 方法名大驼峰
MESSAGE_NAMES_UPPER_CAMEL_CASE: 消息名大驼峰
FIELD_NAMES_LOWER_SNAKE_CASE: 字段名小蛇形
ENUM_FIELD_NAMES_UPPER_SNAKE_CASE: 枚举值名大蛇形
REPEATED_FIELD_NAMES_PLURALIZED: repeated 字段使用复数

配置规则

方法 1: 使用内联注释禁用规则（推荐）

在 .proto 文件中使用注释来禁用特定规则：

// 在文件开头禁用 MAX_LINE_LENGTH 规则（项目规范是 120 字符）
// protolint:disable MAX_LINE_LENGTH

syntax = "proto3";

package jmesh.protocol;

// 对于特定行，可以使用 :next 或 :this
message VeryLongMessageNameThatExceedsTheDefaultLineLengthLimit {
  // protolint:disable:next REPEATED_FIELD_NAMES_PLURALIZED
  repeated string info = 1;  // 这一行不会触发错误（:next 作用于下一行）

  repeated string data = 2;  // protolint:disable:this REPEATED_FIELD_NAMES_PLURALIZED 这一行不会触发错误（:this 作用于当前行）
}

// 重新启用规则
// protolint:enable MAX_LINE_LENGTH

方法 2: 使用自动修复和禁用注释

# 自动修复可以修复的问题，并为其他问题插入禁用注释
protolint lint -fix -auto_disable=next .

方法 3: 使用命令行参数

某些规则可以通过命令行参数调整，例如：

# 查看帮助
protolint lint --help

配置路径

protolint 配置文件应放在 protocol/.protolint.yaml 或项目根目录的 .protolint.yaml。

基本用法：

# 在 protocol 目录下运行
cd protocol
protolint lint .

# 在项目根目录运行，指定配置目录
protolint lint -config_dir_path protocol protocol/

# 指定配置文件路径
protolint lint -config_path protocol/.protolint.yaml protocol/mesh/protocol/route_registry.proto

自动修复

# 自动修复一些问题
protolint lint -fix .

# 自动修复并插入禁用注释（推荐，保持兼容性）
protolint lint -fix -auto_disable=next .

Installation

Via Homebrew
- protolint can be installed for Mac or Linux using Homebrew via the yoheimuta/protolint tap.

brew tap yoheimuta/protolint
brew install protolint

Via GitHub Releases
- You can also download a pre-built binary from this release page: https://github.com/yoheimuta/protolint/releases
- In the downloads section of each release, you can find pre-built binaries in .tar.gz packages.
Use the maintained Docker image
- protolint ships a Docker image yoheimuta/protolint that allows you to use protolint as part of your Docker workflow.

❯❯❯ docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto
[_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto.
[_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style "    ". "  " is correct.
[_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style "    ". "  " is correct.

From Source
- The binary can be installed from source if Go is available. However, I recommend using one of the pre-built binaries instead because it doesn’t include the version info.

go install github.com/yoheimuta/protolint/cmd/protolint@latest

Within JavaScript / TypeScript
- You can use protolint using your nodejs package manager like npm or yarn.

$ npm install protolint --save-dev

This will add a reference to a development dependency to your local package.json.

Within Python projects
- You can use protolint as a linter within your python projects, the wheel protolint-bin on pypi contains the pre-compiled binaries for various platforms. Just add the desired version to your pyproject.toml or requirements.txt.
- The wheels downloaded will contain the compiled go binaries for protolint and protoc-gen-protolint. Your platform must be compatible with the supported binary platforms.
- You can add the linter configuration to the tools.protolint package in pyproject.toml.

Usage

protolint does not require configuration by default, for the majority of projects it should work out of the box.

protolint lint example.proto example2.proto # file mode, specify multiple specific files
protolint lint .                            # directory mode, search for all .proto files recursively
protolint .                                 # same as "protolint lint ."
protolint lint -config_path=path/to/your_protolint.yaml . # use path/to/your_protolint.yaml
protolint lint -config_dir_path=path/to .   # search path/to for .protolint.yaml
protolint lint -fix .                       # automatically fix some of the problems reported by some rules
protolint lint -fix -auto_disable=next .    # this is preferable when you want to fix problems while maintaining the compatibility. Automatically fix some problems and insert disable comments to the other problems. The available values are next and this.
protolint lint -auto_disable=next .         # automatically insert disable comments to the other problems.
protolint lint -v .                         # with verbose output to investigate the parsing error
protolint lint -no-error-on-unmatched-pattern . # exits with success code even if no file is found (file & directory mode)
protolint lint -reporter junit .            # output results in JUnit XML format
protolint lint -output_file=path/to/out.txt # output results to path/to/out.txt
protolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2 .   # run custom lint rules.
protolint list                              # list all current lint rules being used
protolint version                           # print protolint version
protolint --version                         # print protolint version (global flag)
protolint -v                                # print protolint version (when used as the only argument)

Version Control Integration

protolint is available as a pre-commit hook. Add this to your .pre-commit-config.yaml in your repository to run protolint with Go:

repos:
  - repo: https://github.com/yoheimuta/protolint
    rev: v0.56.3 # Select a release here
    hooks:
      - id: protolint

For Docker-based execution, use the protolint-docker hook:

repos:
  - repo: https://github.com/yoheimuta/protolint
    hooks:
      - id: protolint-docker # Uses yoheimuta/protolint:latest by default

Editor Integration

Visual Studio Code
- vscode-protolint
- protolint-vscode
JetBrains IntelliJ IDEA, GoLand, WebStorm, PHPStorm, PyCharm…
- intellij-protolint

Call from Go code

You can also use protolint from Go code. See Go Documentation and lib/lint_test.go in detail.

import (
    "bytes"

    "github.com/yoheimuta/protolint/lib"
)

func main() {
    args := []string{"-config_path", "path/to/your_protolint.yaml", "."}
    var stdout bytes.Buffer
    var stderr bytes.Buffer

    err := lib.Lint(args, &stdout, &stderr)
    if err != nil {
        // Handle error
    }

    // Process output in stdout and stderr
}

Rules

See internal/addon/rules in detail.

The rule set follows:

Official Style Guide. This is enabled by default. Basically, these rules can fix the violations by appending -fix option.
Unofficial Style Guide. This is disabled by default. You can enable each rule with .protolint.yaml.

The -fix option on the command line can automatically fix all the problems reported by fixable rules. See Fixable columns below.

The -auto_disable option on the command line can automatically disable all the problems reported by auto-disable rules. This feature is helpful when fixing the existing violations breaks the compatibility. See AutoDisable columns below.

I recommend that you add all_default: true in .protolint.yaml, because all linters above are automatically enabled so that you can always enjoy maximum benefits whenever protolint is updated.

Run protolint list to see all available rules.

$ protolint list
FILE_HAS_COMMENT: Verifies that a file starts with a doc comment.
SYNTAX_CONSISTENT: Verifies that syntax is a specified version(default is proto3).
FILE_NAMES_LOWER_SNAKE_CASE: Verifies that all file names are lower_snake_case.proto.
QUOTE_CONSISTENT: Verifies that the use of quote for strings is consistent.
ORDER: Verifies that all files should be ordered in the specific manner.
INDENT: Enforces a consistent indentation style.
MAX_LINE_LENGTH: Enforces a maximum line length.
PACKAGE_NAME_LOWER_CASE: Verifies that the package name doesn't contain any uppercase letters.
IMPORTS_SORTED: Enforces sorted imports.
ENUM_FIELD_NAMES_PREFIX: Verifies that enum field names are prefixed with its ENUM_NAME_UPPER_SNAKE_CASE.
ENUM_FIELD_NAMES_UPPER_SNAKE_CASE: Verifies that all enum field names are CAPITALS_WITH_UNDERSCORES.
ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH: Verifies that the zero value enum should have the suffix (e.g. "UNSPECIFIED", "INVALID").
ENUM_FIELDS_HAVE_COMMENT: Verifies that all enum fields have a comment.
ENUM_NAMES_UPPER_CAMEL_CASE: Verifies that all enum names are CamelCase (with an initial capital).
ENUMS_HAVE_COMMENT: Verifies that all enums have a comment.
FIELD_NAMES_LOWER_SNAKE_CASE: Verifies that all field names are underscore_separated_names.
FIELD_NAMES_EXCLUDE_PREPOSITIONS: Verifies that all field names don't include prepositions (e.g. "for", "during", "at").
FIELDS_HAVE_COMMENT: Verifies that all fields have a comment.
PROTO3_FIELDS_AVOID_REQUIRED: Verifies that all fields should avoid required for proto3.
PROTO3_GROUPS_AVOID: Verifies that all groups should be avoided for proto3.
REPEATED_FIELD_NAMES_PLURALIZED: Verifies that repeated field names are pluralized names.
MESSAGE_NAMES_UPPER_CAMEL_CASE: Verifies that all message names are CamelCase (with an initial capital).
MESSAGE_NAMES_EXCLUDE_PREPOSITIONS: Verifies that all message names don't include prepositions (e.g. "With", "For").
MESSAGES_HAVE_COMMENT: Verifies that all messages have a comment.
RPC_NAMES_UPPER_CAMEL_CASE: Verifies that all rpc names are CamelCase (with an initial capital).
RPC_NAMES_CASE: Verifies that all rpc names conform to the specified convention.
RPCS_HAVE_COMMENT: Verifies that all rpcs have a comment.
SERVICE_NAMES_UPPER_CAMEL_CASE: Verifies that all service names are CamelCase (with an initial capital).
SERVICE_NAMES_END_WITH: Verifies that all service names end with the specified value.
SERVICES_HAVE_COMMENT: Verifies that all services have a comment.
FIELD_NUMBERS_ORDER_ASCENDING: Verifies the order of fields.

Examples

Here are some examples that show good style enabled by default. - is a bad style, + is a good style:

ENUM_FIELD_NAMES_PREFIX

enum FooBar {
-  UNSPECIFIED = 0;
+  FOO_BAR_UNSPECIFIED = 0;
}

ENUM_FIELD_NAMES_UPPER_SNAKE_CASE

enum Foo {
-  firstValue = 0;
+  FIRST_VALUE = 0;
-  second_value = 1;
+  SECOND_VALUE = 1;
}

ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH

enum Foo {
-  FOO_FIRST = 0;
+  FOO_UNSPECIFIED = 0;
}

参考：https://github.com/yoheimuta/protolint/issues/256

ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH conforms to the style guide.

The zero value enum should have the suffix `UNSPECIFIED`.

ENUM_NAMES_UPPER_CAMEL_CASE

- enum foobar {
+ enum FooBar {
  FIRST_VALUE = 0;
  SECOND_VALUE = 1;
}

FIELD_NAMES_LOWER_SNAKE_CASE

message SongServerRequest {
-  required string SongName = 1;
+  required string song_name = 1;
}

IMPORTS_SORTED

- import public "new.proto";
+ import "myproject/other_protos.proto";
- import "myproject/other_protos.proto";
+ import public "new.proto";

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

MESSAGE_NAMES_UPPER_CAMEL_CASE

- message song_server_request {
+ message SongServerRequest {
  required string SongName = 1;
  required string song_name = 1;
}

ORDER

- option java_package = "com.example.foo";
- syntax = "proto3";
- package examplePb;
- message song_server_request { }
- import "other.proto";
+ syntax = "proto3";
+ package examplePb;
+ import "other.proto";
+ option java_package = "com.example.foo";
+ message song_server_request { }

PACKAGE_NAME_LOWER_CASE

- package myPackage
+ package my.package

RPC_NAMES_UPPER_CAMEL_CASE

service FooService {
-  rpc get_something(FooRequest) returns (FooResponse);
+  rpc GetSomething(FooRequest) returns (FooResponse);
}

RPC_SERVICES_UPPER_CAMEL_CASE

- service foo_service {
+ service FooService {
  rpc get_something(FooRequest) returns (FooResponse);
  rpc GetSomething(FooRequest) returns (FooResponse);
}

REPEATED_FIELD_NAMES_PLURALIZED

-  repeated string song_name = 1;
+  repeated string song_names = 1;

INDENT

 enum enumAllowingAlias {
   UNKNOWN = 0;
-        option allow_alias = true;
+  option allow_alias = true;
   STARTED = 1;
-     RUNNING = 2 [(custom_option) = "hello world"];
+  RUNNING = 2 [(custom_option) = "hello world"];
- }
+}

-   message TestMessage { string test_field = 1; }
+ message TestMessage {
+  string test_field = 1;
+}

QUOTE_CONSISTENT

 option java_package = "com.example.foo";
- option go_package = 'example';
+ option go_package = "example";

Creating your custom rules

protolint is the pluggable linter so that you can freely create custom lint rules.

A complete sample project (aka plugin) is included in this repo under the _example/plugin directory.

Reporters

protolint comes with several built-in reporters(aka. formatters) to control the appearance of the linting results.

You can specify a reporter using the -reporter flag on the command line. For example, -reporter junit uses the junit reporter.

The built-in reporter options are:

plain (default)
junit
json
sarif
sonar (SonarQube generic issue format)
unix
tsc (compatible to TypeScript compiler)

Configure

Disable rules in a Protocol Buffer file

Rules can be disabled with a comment inside a Protocol Buffer file with the following format. The rules will be disabled until the end of the file or until the linter sees a matching enable comment:

// protolint:disable <ruleID1> [<ruleID2> <ruleID3>...]
...
// protolint:enable <ruleID1> [<ruleID2> <ruleID3>...]

It’s also possible to modify a disable command by appending :next or :this for only applying the command to this(current) or the next line respectively.

For example:

enum Foo {
  // protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
  firstValue = 0;    // no error
  second_value = 1;  // protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
  THIRD_VALUE = 2;   // spits out an error
}

Setting the command-line option -auto_disable to next or this inserts disable commands whenever spotting problems.

You can specify -fix option together. The rules supporting auto_disable suppress the violations instead of fixing them that cause a schema incompatibility.

Config file

protolint can operate using a config file named .protolint.yaml.

Refer to _example/config/.protolint.yaml for the config file specification.

protolint will automatically search a current working directory for the config file by default and successive parent directories all the way up to the root directory of the filesystem. And it can search the specified directory with -config_dir_path flag. It can also search the specified file with --config_path flag.

---
# Lint directives.
lint:
  # Linter files to ignore.
  ignores:
    - id: MESSAGE_NAMES_UPPER_CAMEL_CASE
      files:
        # NOTE: UNIX paths will be properly accepted by both UNIX and Windows.
        - _example/proto/simple.proto
    - id: ENUM_NAMES_UPPER_CAMEL_CASE
      files:
        - path/to/foo.proto

  # Linter files to walk.
  files:
    # The specific files to exclude.
    exclude:
      # NOTE: UNIX paths will be properly accepted by both UNIX and Windows.
      - path/to/file

  # Linter directories to walk.
  directories:
    # The specific directories to exclude.
    exclude:
      # NOTE: UNIX paths will be properly accepted by both UNIX and Windows.
      - path/to/dir

  # Linter rules.
  # Run `protolint list` to see all available rules.
  rules:
    # Determines whether or not to include the default set of linters.
    no_default: true

    # Set the default to all linters. This option works the other way around as no_default does.
    # If you want to enable this option, delete the comment out below and no_default.
    # all_default: true

    # The specific linters to add.
    add:
      - FIELD_NAMES_LOWER_SNAKE_CASE
      - MESSAGE_NAMES_UPPER_CAMEL_CASE
      - MAX_LINE_LENGTH
      - INDENT
      - SERVICE_NAMES_END_WITH
      - FIELD_NAMES_EXCLUDE_PREPOSITIONS
      - MESSAGE_NAMES_EXCLUDE_PREPOSITIONS
      - FILE_NAMES_LOWER_SNAKE_CASE
      - IMPORTS_SORTED
      - PACKAGE_NAME_LOWER_CASE
      - ORDER
      - MESSAGES_HAVE_COMMENT
      - SERVICES_HAVE_COMMENT
      - RPCS_HAVE_COMMENT
      - FIELDS_HAVE_COMMENT
      - PROTO3_FIELDS_AVOID_REQUIRED
      - PROTO3_GROUPS_AVOID
      - REPEATED_FIELD_NAMES_PLURALIZED
      - ENUMS_HAVE_COMMENT
      - ENUM_FIELDS_HAVE_COMMENT
      - SYNTAX_CONSISTENT
      - RPC_NAMES_CASE
      - FILE_HAS_COMMENT
      - QUOTE_CONSISTENT
      - FIELD_NUMBERS_ORDER_ASCENDING

    # The specific linters to remove.
    remove:
      - RPC_NAMES_UPPER_CAMEL_CASE

  # Linter rules option.
  rules_option:
    # MAX_LINE_LENGTH rule option.
    max_line_length:
      # Enforces a maximum line length
      max_chars: 80
      # Specifies the character count for tab characters
      tab_chars: 2

    # INDENT rule option.
    indent:
      # Available styles are 4(4-spaces), 2(2-spaces) or tab.
      style: 4
      # Specifies if it should stop considering and inserting new lines at the appropriate positions
      # when the inner elements are on the same line. Default is false.
      not_insert_newline: true

    # FILE_NAMES_LOWER_SNAKE_CASE rule option.
    file_names_lower_snake_case:
      excludes:
        - ../proto/invalidFileName.proto

    # QUOTE_CONSISTENT rule option.
    quote_consistent:
      # Available quote are "double" or "single".
      quote: double

    # ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH rule option.
    enum_field_names_zero_value_end_with:
      suffix: INVALID

    # SERVICE_NAMES_END_WITH rule option.
    service_names_end_with:
      text: Service

    # FIELD_NAMES_EXCLUDE_PREPOSITIONS rule option.
    field_names_exclude_prepositions:
      # The specific prepositions to determine if the field name includes.
      prepositions:
        - for
        - at
        - of
      # The specific keywords including prepositions to ignore. E.g. end_of_support is a term you would like to use, and skip checking.
      excludes:
        - end_of_support

    # REPEATED_FIELD_NAMES_PLURALIZED rule option.
    ## The spec for each rules follows the implementation of https://github.com/gertd/go-pluralize.
    ## Plus, you can refer to this rule's test code.
    repeated_field_names_pluralized:
      uncountable_rules:
        - paper
      irregular_rules:
        Irregular: Regular

    # MESSAGE_NAMES_EXCLUDE_PREPOSITIONS rule option.
    message_names_exclude_prepositions:
      # The specific prepositions to determine if the message name includes.
      prepositions:
        - With
        - For
        - Of
      # The specific keywords including prepositions to ignore. E.g. EndOfSupport is a term you would like to use, and skip checking.
      excludes:
        - EndOfSupport
        -
    #  RPC_NAMES_CASE rule option.
    rpc_names_case:
      # The specific convention the name should conforms to.
      ## Available conventions are "lower_camel_case", "upper_snake_case", or "lower_snake_case".
      convention: upper_snake_case

    # MESSAGES_HAVE_COMMENT rule option.
    messages_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # SERVICES_HAVE_COMMENT rule option.
    services_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # RPCS_HAVE_COMMENT rule option.
    rpcs_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # FIELDS_HAVE_COMMENT rule option.
    fields_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # ENUMS_HAVE_COMMENT rule option.
    enums_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # ENUM_FIELDS_HAVE_COMMENT rule option.
    enum_fields_have_comment:
      # Comments need to begin with the name of the thing being described. default is false.
      should_follow_golang_style: true

    # SYNTAX_CONSISTENT rule option.
    syntax_consistent:
      # Default is proto3.
      version: proto2

Exit codes

When linting files, protolint will exit with one of the following exit codes:

0: Linting was successful and there are no linting errors.
1: Linting was successful and there is at least one linting error.
2: Linting was unsuccessful due to all other errors, such as parsing, internal, and runtime errors.

Refer

https://github.com/yoheimuta/protolint
Style Guide
Language Guide (proto3)
Language Guide (proto2)
Tutorials

Organizing a Go module

2025-12-28T12:00:00+08:00

Tutorial: Create a Go module
- Prerequisites
- Start a module that others can use
Call your code from another module
Managing module source
Organizing a Go module
Refer

A common question developers new to Go have is “How do I organize my Go project?”, in terms of the layout of files and folders. The goal of this document is to provide some guidelines that will help answer this question. To make the most of this document, make sure you’re familiar with the basics of Go modules by reading Tutorial: Create a Go module and managing module source.

Go projects can include packages, command-line programs or a combination of the two. This guide is organized by project type.

Tutorial: Create a Go module

This is the first part of a tutorial that introduces a few fundamental features of the Go language. If you’re just getting started with Go, be sure to take a look at Tutorial: Get started with Go, which introduces the go command, Go modules, and very simple Go code.

In this tutorial you’ll create two modules. The first is a library which is intended to be imported by other libraries or applications. The second is a caller application which will use the first.

This tutorial’s sequence includes seven brief topics that each illustrate a different part of the language.

Create a module – Write a small module with functions you can call from another module.
Call your code from another module – Import and use your new module.
Return and handle an error – Add simple error handling.
Return a random greeting – Handle data in slices (Go’s dynamically-sized arrays).
Return greetings for multiple people – Store key/value pairs in a map.
Add a test – Use Go’s built-in unit testing features to test your code.
Compile and install the application – Compile and install your code locally.

Note: For other tutorials, see Tutorials.

Prerequisites

Some programming experience. The code here is pretty simple, but it helps to know something about functions, loops, and arrays.
A tool to edit your code. Any text editor you have will work fine. Most text editors have good support for Go. The most popular are VSCode (free), GoLand (paid), and Vim (free).
A command terminal. Go works well using any terminal on Linux and Mac, and on PowerShell or cmd in Windows.

Start a module that others can use

Start by creating a Go module. In a module, you collect one or more related packages for a discrete and useful set of functions. For example, you might create a module with packages that have functions for doing financial analysis so that others writing financial applications can use your work. For more about developing modules, see Developing and publishing modules.

Go code is grouped into packages, and packages are grouped into modules. Your module specifies dependencies needed to run your code, including the Go version and the set of other modules it requires.

As you add or improve functionality in your module, you publish new versions of the module. Developers writing code that calls functions in your module can import the module’s updated packages and test with the new version before putting it into production use.

Open a command prompt and cd to your home directory.

On Linux or Mac:

cd

On Windows:

cd %HOMEPATH%

Create a greetings directory for your Go module source code.

For example, from your home directory use the following commands:

mkdir greetings
cd greetings

Start your module using the go mod init command.

Run the go mod init command, giving it your module path – here, use example.com/greetings. If you publish a module, this must be a path from which your module can be downloaded by Go tools. That would be your code’s repository.

For more on naming your module with a module path, see Managing dependencies.

$ go mod init example.com/greetings
go: creating new go.mod: module example.com/greetings

The go mod init command creates a go.mod file to track your code’s dependencies. So far, the file includes only the name of your module and the Go version your code supports. But as you add dependencies, the go.mod file will list the versions your code depends on. This keeps builds reproducible and gives you direct control over which module versions to use.

In your text editor, create a file in which to write your code and call it greetings.go.

Paste the following code into your greetings.go file and save the file.

package greetings

import "fmt"

// Hello returns a greeting for the named person.
func Hello(name string) string {
    // Return a greeting that embeds the name in a message.
    message := fmt.Sprintf("Hi, %v. Welcome!", name)
    return message
}

This is the first code for your module. It returns a greeting to any caller that asks for one. You’ll write code that calls this function in the next step.

In this code, you:

Declare a greetings package to collect related functions.
Implement a Hello function to return the greeting.

This function takes a name parameter whose type is string. The function also returns a string. In Go, a function whose name starts with a capital letter can be called by a function not in the same package. This is known in Go as an exported name. For more about exported names, see Exported names in the Go tour.

Declare a message variable to hold your greeting.

In Go, the := operator is a shortcut for declaring and initializing a variable in one line (Go uses the value on the right to determine the variable’s type). Taking the long way, you might have written this as:

var message string
message = fmt.Sprintf("Hi, %v. Welcome!", name)

Use the fmt package’s Sprintf function to create a greeting message. The first argument is a format string, and Sprintf substitutes the name parameter’s value for the %v format verb. Inserting the value of the name parameter completes the greeting text.
Return the formatted greeting text to the caller.

In the next step, you’ll call this function from another module.

Call your code from another module

In the previous section, you created a greetings module. In this section, you’ll write code to make calls to the Hello function in the module you just wrote. You’ll write code you can execute as an application, and which calls code in the greetings module.

Create a hello directory for your Go module source code. This is where you’ll write your caller.

After you create this directory, you should have both a hello and a greetings directory at the same level in the hierarchy, like so:

<home>/
 |-- greetings/
 |-- hello/

For example, if your command prompt is in the greetings directory, you could use the following commands:

cd ..
mkdir hello
cd hello

Enable dependency tracking for the code you’re about to write.

To enable dependency tracking for your code, run the go mod init command, giving it the name of the module your code will be in.

For the purposes of this tutorial, use example.com/hello for the module path.

$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello

In your text editor, in the hello directory, create a file in which to write your code and call it hello.go.

Write code to call the Hello function, then print the function’s return value.

To do that, paste the following code into hello.go.

package main

import (
    "fmt"
    "example.com/greetings"
)

func main() {
    // Get a greeting message and print it.
    message := greetings.Hello("Gladys")
    fmt.Println(message)
}

In this code, you:

Declare a main package. In Go, code executed as an application must be in a main package.
Import two packages: example.com/greetings and the fmt package. This gives your code access to functions in those packages. Importing example.com/greetings (the package contained in the module you created earlier) gives you access to the Hello function. You also import fmt, with functions for handling input and output text (such as printing text to the console).
Get a greeting by calling the greetings package’s Hello function.

Edit the example.com/hello module to use your local example.com/greetings module.

For production use, you’d publish the example.com/greetings module from its repository (with a module path that reflected its published location), where Go tools could find it to download it. For now, because you haven’t published the module yet, you need to adapt the example.com/hello module so it can find the example.com/greetings code on your local file system.

To do that, use the go mod edit command to edit the example.com/hello module to redirect Go tools from its module path (where the module isn’t) to the local directory (where it is).

From the command prompt in the hello directory, run the following command:

$ go mod edit -replace example.com/greetings=../greetings

The command specifies that example.com/greetings should be replaced with ../greetings for the purpose of locating the dependency. After you run the command, the go.mod file in the hello directory should include a replace directive:

module example.com/hello

go 1.16

replace example.com/greetings => ../greetings

From the command prompt in the hello directory, run the go mod tidy command to synchronize the example.com/hello module’s dependencies, adding those required by the code, but not yet tracked in the module.

$ go mod tidy
go: found example.com/greetings in example.com/greetings v0.0.0-00010101000000-000000000000

After the command completes, the example.com/hello module’s go.mod file should look like this:

module example.com/hello

go 1.16

replace example.com/greetings => ../greetings

require example.com/greetings v0.0.0-00010101000000-000000000000

The command found the local code in the greetings directory, then added a require directive to specify that example.com/hello requires example.com/greetings. You created this dependency when you imported the greetings package in hello.go.

The number following the module path is a pseudo-version number – a generated number used in place of a semantic version number (which the module doesn’t have yet).

To reference a published module, a go.mod file would typically omit the replace directive and use a require directive with a tagged version number at the end.

require example.com/greetings v1.1.0

For more on version numbers, see Module version numbering.

At the command prompt in the hello directory, run your code to confirm that it works.

$ go run .
Hi, Gladys. Welcome!

Congrats! You’ve written two functioning modules.

Managing module source

When you’re developing modules to publish for others to use, you can help ensure that your modules are easier for other developers to use by following the repository conventions described in this topic.

This topic describes actions you might take when managing your module repository. For information about the sequence of workflow steps you’d take when revising from version to version, see Module release and versioning workflow.

Some of the conventions described here are required in modules, while others are best practices. This content assumes you’re familiar with the basic module use practices described in Managing dependencies.

Go supports the following repositories for publishing modules: Git, Subversion, Mercurial, Bazaar, and Fossil.

For an overview of module development, see Developing and publishing modules.

How Go tools find your published module

In Go’s decentralized system for publishing modules and retrieving their code, you can publish your module while leaving the code in your repository. Go tools rely on naming rules that have repository paths and repository tags indicating a module’s name and version number. When your repository follows these requirements, your module code is downloadable from your repository by Go tools such as the go get command.

When a developer uses the go get command to get source code for packages their code imports, the command does the following:

From import statements in Go source code, go get identifies the module path within the package path.
Using a URL derived from the module path, the command locates the module source on a module proxy server or at its repository directly.
Locates source for the module version to download by matching the module’s version number to a repository tag to discover the code in the repository. When a version number to use is not yet known, go get locates the latest release version.
Retrieves module source and downloads it to the developer’s local module cache.

Organizing code in the repository

You can keep maintenance simple and improve developers’ experience with your module by following the conventions described here. Getting your module code into a repository is generally as simple as with other code.

The following diagram illustrates a source hierarchy for a simple module with two packages.

Your initial commit should include files listed in the following table:

From the command-line, you can create an empty repository, add the files that will be part of your initial commit, and commit with a message. Here’s an example using git:

$ git init
$ git add --all
$ git commit -m "mycode: initial commit"
$ git push

Choosing repository scope

You publish code in a module when the code should be versioned independently from code in other modules.

Designing your repository so that it hosts a single module at its root directory will help keep maintenance simpler, particularly over time as you publish new minor and patch versions, branch into new major versions, and so on. However, if your needs require it, you can instead maintain a collection of modules in a single repository.

Sourcing one module per repository

You can maintain a repository that has a single module’s source in it. In this model, you place your go.mod file at the repository root, with package subdirectories containing Go source beneath.

This is the simplest approach, making your module likely easier to manage over time. It helps you avoid the need to prefix a module version number with a directory path.

Sourcing multiple modules in a single repository

You can publish multiple modules from a single repository. For example, you might have code in a single repository that constitutes multiple modules, but want to version those modules separately.

Each subdirectory that is a module root directory must have its own go.mod file.

Sourcing module code in subdirectories changes the form of the version tag you must use when publishing a module. You must prefix the version number part of the tag with the name of the subdirectory that is the module root. For more about version numbers, see Module version numbering.

For example, for module example.com/mymodules/module1 below, you would have the following for version v1.2.3:

Module path: example.com/mymodules/module1
Version tag: module1/v1.2.3
Package path imported by a user: example.com/mymodules/module1/package1
Module path and version as specified in a user’s require directive: example.com/mymodules/module1 v1.2.3

Organizing a Go module

Basic package

A basic Go package has all its code in the project’s root directory. The project consists of a single module, which consists of a single package. The package name matches the last path component of the module name. For a very simple package requiring a single Go file, the project structure is:

project-root-directory/
  go.mod
  modname.go
  modname_test.go

Assuming this directory is uploaded to a GitHub repository at github.com/someuser/modname, the module line in the go.mod file should say module github.com/someuser/modname.

The code in modname.go declares the package with:

package modname

// ... package code here

Users can then rely on this package by import-ing it in their Go code with:

import "github.com/someuser/modname"

A Go package can be split into multiple files, all residing within the same directory, e.g.:

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth.go
  auth_test.go
  hash.go
  hash_test.go

All the files in the directory declare package modname.

Basic command

A basic executable program (or command-line tool) is structured according to its complexity and code size. The simplest program can consist of a single Go file where func main is defined. Larger programs can have their code split across multiple files, all declaring package main:

project-root-directory/
  go.mod
  auth.go
  auth_test.go
  client.go
  main.go

Here the main.go file contains func main, but this is just a convention. The “main” file can also be called modname.go (for an appropriate value of modname) or anything else.

Assuming this directory is uploaded to a GitHub repository at github.com/someuser/modname, the module line in the go.mod file should say:

module github.com/someuser/modname

And a user should be able to install it on their machine with:

$ go install github.com/someuser/modname@latest

Package or command with supporting packages

Larger packages or commands may benefit from splitting off some functionality into supporting packages. Initially, it’s recommended placing such packages into a directory named internal; this prevents other modules from depending on packages we don’t necessarily want to expose and support for external uses. Since other projects cannot import code from our internal directory, we’re free to refactor its API and generally move things around without breaking external users. The project structure for a package is thus:

project-root-directory/
  internal/
    auth/
      auth.go
      auth_test.go
    hash/
      hash.go
      hash_test.go
  go.mod
  modname.go
  modname_test.go

The modname.go file declares package modname, auth.go declares package auth and so on. modname.go can import the auth package as follows:

import "github.com/someuser/modname/internal/auth"

The layout for a command with supporting packages in an internal directory is very similar, except that the file(s) in the root directory declare package main.

Multiple packages

A module can consist of multiple importable packages; each package has its own directory, and can be structured hierarchically. Here’s a sample project structure:

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
    token/
      token.go
      token_test.go
  hash/
    hash.go
  internal/
    trace/
      trace.go

As a reminder, we assume that the module line in go.mod says:

module github.com/someuser/modname

The modname package resides in the root directory, declares package modname and can be imported by users with:

import "github.com/someuser/modname"

Sub-packages can be imported by users as follows:

import "github.com/someuser/modname/auth"
import "github.com/someuser/modname/auth/token"
import "github.com/someuser/modname/hash"

Package trace that resides in internal/trace cannot be imported outside this module. It’s recommended to keep packages in internal as much as possible.

Multiple commands

Multiple programs in the same repository will typically have separate directories:

project-root-directory/
  go.mod
  internal/
    ... shared internal packages
  prog1/
    main.go
  prog2/
    main.go

In each directory, the program’s Go files declare package main. A top-level internal directory can contain shared packages used by all commands in the repository.

Users can install these programs as follows:

$ go install github.com/someuser/modname/prog1@latest
$ go install github.com/someuser/modname/prog2@latest

A common convention is placing all commands in a repository into a cmd directory; while this isn’t strictly necessary in a repository that consists only of commands, it’s very useful in a mixed repository that has both commands and importable packages, as we will discuss next.

Packages and commands in the same repository

Sometimes a repository will provide both importable packages and installable commands with related functionality. Here’s a sample project structure for such a repository:

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
  internal/
    ... internal packages
  cmd/
    prog1/
      main.go
    prog2/
      main.go

Assuming this module is called github.com/someuser/modname, users can now both import packages from it:

import "github.com/someuser/modname"
import "github.com/someuser/modname/auth"

And install programs from it:

$ go install github.com/someuser/modname/cmd/prog1@latest
$ go install github.com/someuser/modname/cmd/prog2@latest

Server project

Go is a common language choice for implementing servers. There is a very large variance in the structure of such projects, given the many aspects of server development: protocols (REST? gRPC?), deployments, front-end files, containerization, scripts and so on. We will focus our guidance here on the parts of the project written in Go.

Server projects typically won’t have packages for export, since a server is usually a self-contained binary (or a group of binaries). Therefore, it’s recommended to keep the Go packages implementing the server’s logic in the internal directory. Moreover, since the project is likely to have many other directories with non-Go files, it’s a good idea to keep all Go commands together in a cmd directory:

project-root-directory/
  go.mod
  internal/
    auth/
      ...
    metrics/
      ...
    model/
      ...
  cmd/
    api-server/
      main.go
    metrics-analyzer/
      main.go
    ...
  ... the project's other directories with non-Go code

In case the server repository grows packages that become useful for sharing with other projects, it’s best to split these off to separate modules.

Refer

Being Confused About When To Use Generics

2025-12-26T12:30:00+08:00

Concepts
Common uses and misuses
Conclusion
Refer

Generics is a fresh addition to the language. In a nutshell, it allows writing code with types that can be specified later and instantiated when needed. However, it can be pretty easy to be confused about when to use generics and when not to. Throughout this post, we will describe the concept of generics in Go and then delve into common use and misuses.

核心观点：依赖泛型和类型参数可以避免编写提取元素或行为的样板代码。但是，不要过早使用类型参数，只有在看到具体需要时才使用它们。否则，它们会引入不必要的抽象和复杂性。

Concepts

Consider the following function that extracts all the keys from a map[string]int type:

func getKeys(m map[string]int) []string {
    var keys []string
    for k := range m {
        keys = append(keys, k)
    }
    return keys
}

What if we would like to use a similar feature for another map type such as a map[int]string? Before generics, Go developers had a couple of options: using code generation, reflection, or duplicating code.

For example, we could write two functions, one for each map type, or even try to extend getKeys to accept different map types:

func getKeys(m any) ([]any, error) {
    switch t := m.(type) {
    default:
        return nil, fmt.Errorf("unknown type: %T", t)
    case map[string]int:
        var keys []any
        for k := range t {
            keys = append(keys, k)
        }
        return keys, nil
    case map[int]string:
        // Copy the extraction logic
    }
}

We can start noticing a couple of issues: (三个问题)

First, it increases boilerplate code. Indeed, whenever we want to add a case, it will require duplicating the range loop.
Meanwhile, the function now accepts an empty interface, which means we are losing some of the benefits of Go being a typed language. Indeed, checking whether a type is supported is done at runtime instead of compile-time. Hence, we also need to return an error if the provided type is unknown.
Last but not least, as the key type can be either int or string, we are obliged to return a slice of empty interfaces to factor out key types. This approach increases the effort on the caller-side as the client may also have to perform a type check of the keys or extra conversion.

Thanks to generics, we can now refactor this code using type parameters.

Type parameters are generic types we can use with functions and types. For example, the following function accepts a type parameter:

func foo[T any](t T) {
    // ...
}

When calling foo, we will pass a type argument of any type. Passing a type argument is called instantiation because the work is done at compile time which keeps type safety as part of the core language features and avoids runtime overheads.

Let’s get back to the getKeys function and use type parameters to write a generic version that would accept any kind of map:

func getKeys[K comparable, V any](m map[K]V) []K {
  var keys []K
  for k := range m {
    keys = append(keys, k)
  }
  return keys
}

To handle the map, we defined two kinds of type parameters. First, the values can be of any type: V any. However, in Go, the map keys can’t be of any type. For example, we cannot use slices:

var m map[[]byte]int

This code leads to a compilation error: invalid map key type []byte. Therefore, instead of accepting any key type, we are obliged to restrict type arguments so that the key type meets specific requirements. Here, being comparable (we can use == or !=). Hence, we defined K as comparable instead of any.

Restricting type arguments to match specific requirements is called a constraint. A constraint is an interface type that can contain:

A set of behaviors (methods)
But also arbitrary type

Let’s see a concrete example for the latter. Imagine we don’t want to accept any comparable type for map key type. For instance, we would like to restrict it to either int or string types. We can define a custom constraint this way:

type customConstraint interface {
   ~int | ~string // Define a custom type that will restrict types to int and string
}

// Change the type parameter K to be custom
func getKeys[K customConstraint, V any](m map[K]V) []K {
   // Same implementation
}

First, we define a customConstraint interface to restrict the types to be either int or string using the union operator | (we will discuss the use of ~ a bit later). Then, K is now a customConstraint instead of a comparable as before.

Now, the signature of getKeys enforces that we can call it with a map of any value type, but the key type has to be an int or a string. For example, on the caller-side:

m = map[string]int{
   "one":   1,
   "two":   2,
   "three": 3,
}
keys := getKeys(m)

Note that Go can infer that getKeys is called with a string type argument. The previous call was similar to this:

keys := getKeys[string](m)

Let’s also note the constraints package contains a set of common constraints such as Signed that includes all the signed integer types. Let’s ensure that a constraint doesn’t already exist in this package before creating a new one.

So far, we have discussed examples using generics for functions. However, we can also use generics with data structures.

For example, we will create a linked list containing values of any type. Meanwhile, we will write an Add method to append a node:

type Node[T any] struct { // Use type parameter
   Val  T
   next *Node[T]
}

func (n *Node[T]) Add(next *Node[T]) { // Instantiate type receiver
   n.next = next
}

We use type parameters to define T and use both fields in Node. Regarding the method, the receiver is instantiated. Indeed, because Node is generic, it has to follow also the type parameter defined.

One last thing to note about type parameters: they can’t be used on methods, only on functions. For example, the following method wouldn’t compile:

type Foo struct {}

func (Foo) bar[T any](t T) {}

./main.go:29:15: methods cannot have type parameters

Now, let’s delve into concrete cases where we should and shouldn’t use generics.

Common uses and misuses

So when are generics useful? Let’s discuss a couple of common uses where generics are recommended:

Data structures. For example, we can use generics to factor out the element type if we implement a binary tree, a linked list, or a heap.
Functions working with slices, maps, and channels of any type. For example, a function to merge two channels would work with any channel type. Hence, we could use type parameters to factor out the channel type:

func merge[T any](ch1, ch2 <-chan T) <-chan T {
    // ...
}

Meanwhile, instead of factoring out a type, we can factor out behaviors. For example, the sort package contains functions to sort different slice types such as sort.Ints or sort.Float64s. Using type parameters, we can factor out the sorting behaviors that rely on three methods, Len, Less, and Swap:

type sliceFn[T any] struct { // Use type parameter
   s       []T
   compare func(T, T) bool // Compare two T elements
}

func (s sliceFn[T]) Len() int           { return len(s.s) }
func (s sliceFn[T]) Less(i, j int) bool { return s.compare(s.s[i], s.s[j]) }
func (s sliceFn[T]) Swap(i, j int)      { s.s[i], s.s[j] = s.s[j], s.s[i] }

Conversely, when is it recommended not to use generics?

When just calling a method of the type argument. For example, consider a function that receives an io.Writer and call the Write method:

func foo[T io.Writer](w T) {
   b := getBytes()
   _, _ = w.Write(b)
}

When it makes our code more complex. Generics are never mandatory(强制性的), and as Go developers, we have been able to live without them for more than a decade. If writing generic functions or structures we figure out that it doesn’t make our code clearer, we should probably reconsider our decision for this particular use case.

Conclusion

Though generics can be very helpful in particular conditions, we should be cautious about when to use them and not use them.

In general, when we want to answer when not to use generics, we can find similarities with when not to use interfaces. Indeed, generics introduce a form of abstraction, and we have to remember that unnecessary abstractions introduce complexity.

Let’s not pollute our code with needless abstractions, and let’s focus on solving concrete problems for now. It means that we shouldn’t use type parameters prematurely. Let’s wait until we are about to write boilerplate code to consider using generics.

Refer

How to Achieve Concurrency

2025-12-25T08:30:00+08:00

并发的核心定义
Go 语言的两大核心并发特性
通道（Channels）的工作机制
主要优势
总结
Refer

本文介绍了 Go 语言如何通过其核心机制实现高效的并发编程。对比了传统同步处理文件的低效性，并展示了如何利用 Goroutines 这种轻量级线程来独立执行多个任务。为了管理这些并发操作，程序使用 Channels 作为数据通信的管道，在不同任务之间安全地传递结果。这种设计允许程序在数据准备就绪前自动阻塞等待，从而简化了复杂的异步逻辑。通过结合这两大特性，开发者可以更轻松地构建高性能且结构简洁的应用程序。

传统的编程就像只有一个厨师的厨房，他必须切完所有的菜才能开始炒菜，非常耗时。而 Go 语言的并发就像是请了一群助手（Goroutines），每个助手负责处理一样食材，并把处理好的食材通过一条传送带（Channels）送到主厨面前。主厨不需要时刻盯着助手，他只需要在传送带末端等着，有食材送达时再继续下一步工作，这大大提升了整个厨房的出菜速度。

并发的核心定义

并发（Concurrency）独立地处理多个任务。相比于传统的同步执行（按顺序一个接一个地等待任务完成），并发可以显著提高处理 I/O 密集型任务（如读取文件）的效率。

Go 语言的两大核心并发特性

Go 语言通过内置的两个功能简化了异步编程：

Goroutines（协程）：可以被视为一种极其高效的线程。通过在函数调用前使用 go 关键字，程序可以为每个任务启动一个 goroutine，从而实现并发执行。
Channels（通道）：通道是用于在 goroutines 之间发送和接收数据的工具，它确保了数据流动的有序性。

通道（Channels）的工作机制

管道比喻：来源将通道比作一根管道（Pipe），一端用于发送数据，另一端用于接收数据。
自动同步功能：通道不仅负责传递结果（如错误信息或成功标志），还起到了协调执行顺序的作用。当代码尝试从通道接收值时，它会自动进入等待状态，直到有数据到达才会继续执行，这保证了程序不会在任务完成前尝试打印结果,。

主要优势

使用 goroutines 和 channels 可以极大简化应用程序中的异步编程，使开发者能够以更简单、更直观的方式编写高效的并发代码。

总结

想象有这样一场接力赛：

准备阶段：明确要分头行动（并发概念）。
起跑：多名运动员（Goroutines）同时出发，不再排队等候。
传递信息：运动员通过接力棒（Channels）传递处理好的信息。
终点汇总：裁判（主程序）在终点线等待，只有接到接力棒时才会记录成绩（自动同步），确保不会在比赛结束前宣布结果。

Refer

How to achieve concurrency
https://www.youtube.com/@golang
https://notebooklm.google.com/notebook/de556dc2-5421-4a1d-b3b0-d6f3b44ad564 (NotebookLM 解读)

100 Go Mistakes and How to Avoid Them

2025-12-24T20:30:00+08:00

Code and Project Organization
Data Types
- 17. Creating confusion with octal literals
Refer

Source code and community space of 📖 100 Go Mistakes and How to Avoid Them, published by Manning in August 2022. Read online: 100go.co

Meanwhile, it’s also open to the community. If you believe that a common Go mistake should be added, please create an issue.

Code and Project Organization

1. Unintended variable shadowing (变量遮蔽)

TL;DR

Avoiding shadowed variables can help prevent mistakes like referencing the wrong variable or confusing readers.

Variable shadowing occurs when a variable name is redeclared in an inner block, but this practice is prone to mistakes. Imposing a rule to forbid shadowed variables depends on personal taste. For example, sometimes it can be convenient to reuse an existing variable name like err for errors. Yet, in general, we should remain cautious because we now know that we can face a scenario where the code compiles, but the variable that receives the value is not the one expected.

代码示例：

package main

import (
	"log"
	"net/http"
)

func main() {
	_ = listing1()
	_ = listing2()
	_ = listing3()
	_ = listing4()
}

func listing1() error {
	var client *http.Client
	if tracing {
		client, err := createClientWithTracing()
		if err != nil {
			return err
		}
		log.Println(client)
	} else {
		client, err := createDefaultClient()
		if err != nil {
			return err
		}
		log.Println(client)
	}

	_ = client
	return nil
}

func listing2() error {
	var client *http.Client
	if tracing {
		c, err := createClientWithTracing()
		if err != nil {
			return err
		}
		client = c
	} else {
		c, err := createDefaultClient()
		if err != nil {
			return err
		}
		client = c
	}

	_ = client
	return nil
}

func listing3() error {
	var client *http.Client
	var err error
	if tracing {
		client, err = createClientWithTracing()
		if err != nil {
			return err
		}
	} else {
		client, err = createDefaultClient()
		if err != nil {
			return err
		}
	}

	_ = client
	return nil
}

func listing4() error {
	var client *http.Client
	var err error
	if tracing {
		client, err = createClientWithTracing()
	} else {
		client, err = createDefaultClient()
	}
	if err != nil {
		return err
	}

	_ = client
	return nil
}

var tracing bool

func createClientWithTracing() (*http.Client, error) {
	return nil, nil
}

func createDefaultClient() (*http.Client, error) {
	return nil, nil
}

问题解析：

在 listing1() 中出现了变量遮蔽问题：:= 操作符在 if 块内创建了新的局部变量 client，而不是修改外部的 client 变量。所以外部 client 始终是 nil。

func listing1() error {
    var client *http.Client  // 外部声明的 client 变量
    if tracing {
        // 这里使用 := 重新声明了新的 client 和 err 变量
        client, err := createClientWithTracing()  // 这里创建了新的 client 变量
        if err != nil {
            return err
        }
        log.Println(client)  // 打印的是内部 client
    }
    // ...
    _ = client  // 这里使用的是外部的 client，仍然是 nil！
    return nil
}

优化方案：

解决方案1：listing2()。使用不同的变量名 c 接收返回值，然后赋值给外部 client，避免变量遮蔽，但需要额外的临时变量。
解决方案2：listing3()。预先声明所有变量，使用赋值操作符 = 而不是短声明 :=，代码较冗长，错误处理重复。
最佳实践：listing4()。预先声明变量，逻辑与错误处理分离，最简洁，避免重复代码。

避免遮蔽的建议：

使用 IDE 或 linter 工具检测遮蔽
考虑禁用变量遮蔽的代码规范
除非有明确理由，否则避免重用变量名

2. Unnecessary nested code (代码嵌套过深)

TL;DR

Avoiding nested levels and keeping the happy path aligned on the left makes building a mental code model easier.

In general, the more nested levels a function requires, the more complex it is to read and understand. Let’s see some different applications of this rule to optimize our code for readability:

When an if block returns, we should omit the else block in all cases. For example, we shouldn’t write:

if foo() {
    // ...
    return true
} else {
    // ...
}

Instead, we omit the else block like this:

if foo() {
    // ...
    return true
}
// ...

We can also follow this logic with a non-happy path:

if s != "" {
    // ...
} else {
    return errors.New("empty string")
}

Here, an empty s represents the non-happy path. Hence, we should flip the condition like so:

if s == "" {
    return errors.New("empty string")
}
// ...

Writing readable code is an important challenge for every developer. Striving to reduce the number of nested blocks, aligning the happy path on the left, and returning as early as possible are concrete means to improve our code’s readability.

代码示例：

package main

import "errors"

// 反面示例
func join1(s1, s2 string, max int) (string, error) {
	if s1 == "" {
		return "", errors.New("s1 is empty")
	} else {
		if s2 == "" {
			return "", errors.New("s2 is empty")
		} else {
			concat, err := concatenate(s1, s2)
			if err != nil {
				return "", err
			} else {
				if len(concat) > max {
					return concat[:max], nil
				} else {
					return concat, nil
				}
			}
		}
	}
}

// 建议用法
func join2(s1, s2 string, max int) (string, error) {
	if s1 == "" {
		return "", errors.New("s1 is empty")
	}
	if s2 == "" {
		return "", errors.New("s2 is empty")
	}
	concat, err := concatenate(s1, s2)
	if err != nil {
		return "", err
	}
	if len(concat) > max {
		return concat[:max], nil
	}
	return concat, nil
}

func concatenate(s1, s2 string) (string, error) {
	return "", nil
}

3. Misusing init functions (init 函数误用)

TL;DR

When initializing variables, remember that init functions have limited error handling and make state handling and testing more complex. In most cases, initializations should be handled as specific functions.

An init function is a function used to initialize the state of an application. It takes no arguments and returns no result (a func() function). When a package is initialized, all the constant and variable declarations in the package are evaluated. Then, the init functions are executed.

Init functions can lead to some issues:

They can limit error management.
They can complicate how to implement tests (for example, an external dependency must be set up, which may not be necessary for the scope of unit tests).
If the initialization requires us to set a state, that has to be done through global variables.

We should be cautious with init functions. They can be helpful in some situations, however, such as defining static configuration. Otherwise, and in most cases, we should handle initializations through ad hoc functions.

init 函数是 Go 语言中的特殊函数，用于包初始化：

无参数，无返回值
在程序启动时自动执行
一个包可以有多个 init 函数，按声明顺序执行
执行时机：包级变量初始化后，main 函数执行前

示例1：多个 init 函数

// main.go
package main

import (
	"fmt"
	"github.com/teivah/100-go-mistakes/src/02-code-project-organization/3-init-functions/redis"
)

func init() {
	fmt.Println("init 1")  // 第二个执行
}

func init() {
	fmt.Println("init 2")  // 第三个执行
}

func main() {
	err := redis.Store("foo", "bar")
	_ = err
}

// redis.go
package redis

import "fmt"

func init() {
	fmt.Println("redis")  // 第一个执行
}

func Store(key, value string) error {
	return nil
}

执行顺序：

导入 redis 包 → 执行 redis.init()
执行 main 包的 init 函数（按声明顺序）
执行 main 函数

输出：

redis
init 1
init 2

示例2：数据库连接初始化

package main

import (
	"database/sql"
	"log"
	"os"
)

var db *sql.DB  // 全局变量

func init() {
	dataSourceName := os.Getenv("MYSQL_DATA_SOURCE_NAME")
	d, err := sql.Open("mysql", dataSourceName)
	if err != nil {
		log.Panic(err)  // 错误处理受限
	}
	err = d.Ping()
	if err != nil {
		log.Panic(err)  // 只能 panic，无法优雅处理
	}
	db = d  // 必须使用全局变量
}

func createClient(dataSourceName string) (*sql.DB, error) {
	db, err := sql.Open("mysql", dataSourceName)
	if err != nil {
		return nil, err
	}
	if err = db.Ping(); err != nil {
		return nil, err
	}
	return db, nil
}

init 函数的问题：

init 函数错误处理受限。如果初始化失败，只能 panic，无法返回错误给调用者，程序直接崩溃

func init() {
	// 如果初始化失败，只能 panic
	// 无法返回错误给调用者
	log.Panic(err)  // 程序直接崩溃
}

// 对比普通函数
func initDB() error {
	// 可以返回错误，让调用者决定如何处理
	return errors.New("connection failed")
}

测试复杂化
- 自动执行，无法控制时机
- 依赖全局变量，测试相互影响
- 需要设置环境变量，测试配置复杂

// 测试时需要：go test -env "MYSQL_DATA_SOURCE_NAME=..."
// 或者需要模拟全局状态

依赖全局变量
- 全局状态难以维护
- 并发安全问题
- 代码耦合度高

var db *sql.DB  // 全局变量

func init() {
	db = d  // 必须用全局变量存储状态
}

执行顺序不可控

// 多个包的 init 函数执行顺序
// 由导入依赖决定，不易理解和维护
package A: init() → package B: init() → main.init()

init 函数的适用场景：

package config

var DefaultConfig Config

func init() {
	// 初始化静态配置（无外部依赖）
	DefaultConfig = Config{
		Timeout: 30 * time.Second,
		MaxConn: 100,
	}
}

合理用途：

静态配置初始化
验证包级变量合理性
注册驱动（如 database/sql 驱动注册）
设置默认行为

不适合的情况：

// 不适合：有外部依赖的初始化
func init() {
	// 从环境变量读取配置（可能有环境依赖）
	// 连接数据库（可能失败，需要错误处理）
	// 启动网络服务（应延迟初始化）
}

最佳实践建议：

使用显式初始化函数

// 更好的方式
type App struct {
    db *sql.DB
    // 其他依赖
}

func NewApp() (*App, error) {
    db, err := createClient(os.Getenv("MYSQL_DATA_SOURCE_NAME"))
    if err != nil {
        return nil, fmt.Errorf("init db: %w", err)
    }
    return &App{db: db}, nil
}

func main() {
    app, err := NewApp()
    if err != nil {
        log.Fatal(err)  // 可控的错误处理
    }
    // 使用 app
}

依赖注入

func CreateDB(dataSourceName string) (*sql.DB, error) {
    // 可测试，可控制
}

func main() {
    db, err := CreateDB(os.Getenv("MYSQL_DATA_SOURCE_NAME"))
    if err != nil {
        // 优雅处理
    }
}

配置对象模式

type Config struct {
    DBDataSource string
    // 其他配置
}

func LoadConfig() (Config, error) {
    // 显式加载配置，可返回错误
}

func main() {
    cfg, err := LoadConfig()
    if err != nil {
        // 处理错误
    }
    db, err := createClient(cfg.DBDataSource)
    // ...
}

总结：

init 函数的主要问题：

错误处理能力差：只能 panic，无法优雅处理
测试困难：自动执行，依赖全局状态
隐式行为：代码逻辑不明显，维护困难
执行顺序依赖：由导入顺序决定，不易理解

建议：除非是简单的静态初始化，否则使用显式初始化函数，这样代码更清晰、更可测试、错误处理更完善。

4. Overusing getters and setters (过度使用 Getter/Setter)

TL;DR

Forcing the use of getters and setters isn’t idiomatic in Go. Being pragmatic and finding the right balance between efficiency and blindly following certain idioms should be the way to go.

Data encapsulation refers to hiding the values or state of an object. Getters and setters are means to enable encapsulation by providing exported methods on top of unexported object fields.

In Go, there is no automatic support for getters and setters as we see in some languages. It is also considered neither mandatory nor idiomatic to use getters and setters to access struct fields. We shouldn’t overwhelm our code with getters and setters on structs if they don’t bring any value. We should be pragmatic and strive to find the right balance between efficiency and following idioms that are sometimes considered indisputable in other programming paradigms.

Remember that Go is a unique language designed for many characteristics, including simplicity. However, if we find a need for getters and setters or, as mentioned, foresee a future need while guaranteeing forward compatibility, there’s nothing wrong with using them.

Go 语言的设计哲学强调简洁和实用，不强制使用 getter 和 setter。这与 Java 等语言形成鲜明对比。

Go 语言的独特设计：

没有自动属性支持

// Java风格（自动属性）
private String name;
public String getName() { return name; }
public void setName(String name) { this.name = name; }

// Go风格（直接访问或手动方法）
type Person struct {
    Name string  // 直接导出，简单情况
}

访问控制通过大小写实现

// 导出字段（公开）
type Person struct {
    Name string    // 大写开头 - 公开访问
    Age  int       // 大写开头 - 公开访问
}

// 非导出字段（私有）
type person struct {
    name string    // 小写开头 - 包内访问
    age  int       // 小写开头 - 包内访问
}

何时使用 Getter/Setter？

适合使用的情况1：需要验证逻辑

type BankAccount struct {
    balance float64  // 私有，需要保护
}

// Getter
func (b *BankAccount) Balance() float64 {
    return b.balance
}

// Setter（带验证）
func (b *BankAccount) Deposit(amount float64) error {
    if amount <= 0 {
        return fmt.Errorf("存款金额必须为正数")
    }
    b.balance += amount
    return nil
}

func (b *BankAccount) Withdraw(amount float64) error {
    if amount <= 0 {
        return fmt.Errorf("取款金额必须为正数")
    }
    if amount > b.balance {
        return fmt.Errorf("余额不足")
    }
    b.balance -= amount
    return nil
}

适合使用的情况2：需要计算或派生值

type Rectangle struct {
    width  float64
    height float64
}

// Getter（计算值）
func (r *Rectangle) Area() float64 {
    return r.width * r.height
}

func (r *Rectangle) Perimeter() float64 {
    return 2 * (r.width + r.height)
}

适合使用的情况3：需要延迟初始化或缓存

type ExpensiveResource struct {
    mu     sync.RWMutex
    data   []byte
    loaded bool
}

// Getter（延迟加载）
func (e *ExpensiveResource) Data() ([]byte, error) {
    e.mu.RLock()
    if e.loaded {
        data := e.data
        e.mu.RUnlock()
        return data, nil
    }
    e.mu.RUnlock()

    // 加写锁并加载
    e.mu.Lock()
    defer e.mu.Unlock()

    if !e.loaded {
        var err error
        e.data, err = loadExpensiveData()
        if err != nil {
            return nil, err
        }
        e.loaded = true
    }
    return e.data, nil
}

不需要使用的情况

简单数据传输对象（DTO）

// 直接导出字段更简洁
type Point struct {
    X int
    Y int
}

// 使用简单明了
p := Point{X: 10, Y: 20}
fmt.Printf("Point: (%d, %d)\n", p.X, p.Y)

配置结构

type Config struct {
    Host     string
    Port     int
    Timeout  time.Duration
    MaxConns int
}

// 直接初始化更清晰
config := Config{
    Host:     "localhost",
    Port:     8080,
    Timeout:  30 * time.Second,
    MaxConns: 100,
}

内部辅助结构

// 只在包内使用，可以直接访问
type internalState struct {
    counter    int
    lastUpdate time.Time
    active     bool
}

func (is *internalState) increment() {
    is.counter++
    is.lastUpdate = time.Now()
}

总结建议

默认直接导出字段：Go 社区倾向于简单直接的访问方式
有理由时才封装：
- 需要验证逻辑
- 需要维护不变性
- 需要派生计算值
- 涉及并发安全
保持 API 稳定：如果结构体是公开 API 的一部分，提前考虑是否需要封装
信任使用者：Go 哲学假设开发者知道自己在做什么，不过度保护
文档说明：通过文档说明约束，而不是强制封装

Go 语言的这种务实态度正是其魅力所在——在简洁性和封装性之间找到平衡，避免不必要的复杂性。

5. Interface pollution (接口污染)

TL;DR

Abstractions should be discovered, not created. To prevent unnecessary complexity, create an interface when you need it and not when you foresee needing it, or if you can at least prove the abstraction to be a valid one.

More: Interface pollution
NotebookML 解读：https://notebooklm.google.com/notebook/d86b149b-bc4d-4587-9a75-7083db063b62?authuser=1

Interfaces are one of the cornerstones(基石) of the Go language when designing and structuring our code. However, like many tools or concepts, abusing them is generally not a good idea. Interface pollution is about overwhelming our code with unnecessary abstractions, making it harder to understand. It’s a common mistake made by developers coming from another language with different habits. Before delving into the topic, let’s refresh our minds about Go’s interfaces. Then, we will see when it’s appropriate to use interfaces and when it may be considered pollution.

Go 语言中 “接口污染” 的概念，即过度或不必要地使用接口，反而会让代码变得复杂难懂。核心观点是：接口的抽象应该是“被发现”，而不是“被创造”。

Concepts (interface)

An interface provides a way to specify the behavior of an object. We use interfaces to create common abstractions that multiple objects can implement. What makes Go interfaces so different is that they are satisfied implicitly. There is no explicit keyword like implements to mark that an object X implements interface Y.

To understand what makes interfaces so powerful, we will dig into two popular ones from the standard library: io.Reader and io.Writer. The io package provides abstractions for I/O primitives. Among these abstractions, io.Reader relates to reading data from a data source and io.Writer to writing data to a target, as represented in the next figure:

The io.Reader contains a single Read method:

type Reader interface {
    Read(p []byte) (n int, err error)
}

Custom implementations of the io.Reader interface should accept a slice of bytes, filling it with its data and returning either the number of bytes read or an error.

On the other hand, io.Writer defines a single method, Write:

type Writer interface {
    Write(p []byte) (n int, err error)
}

Custom implementations of io.Writer should write the data coming from a slice to a target and return either the number of bytes written or an error. Therefore, both interfaces provide fundamental abstractions:

io.Reader reads data from a source
io.Writer writes data to a target

What is the rationale(根本原因) for having these two interfaces in the language? What is the point of creating these abstractions?

Let’s assume we need to implement a function that should copy the content of one file to another. We could create a specific function that would take as input two *os.File. Or, we can choose to create a more generic function using io.Reader and io.Writer abstractions:

func copySourceToDest(source io.Reader, dest io.Writer) error {
    // ...
}

This function would work with *os.File parameters (as *os.File implements both io.Reader and io.Writer) and any other type that would implement these interfaces. For example, we could create our own io.Writer that writes to a database, and the code would remain the same. It increases the genericity of the function; hence, its reusability.

Furthermore, writing a unit test for this function is easier because, instead of having to handle files, we can use the strings and bytes packages that provide helpful implementations:

func TestCopySourceToDest(t *testing.T) {
    const input = "foo"
    source := strings.NewReader(input) // Creates an io.Reader
    dest := bytes.NewBuffer(make([]byte, 0)) // Creates an io.Writer

    err := copySourceToDest(source, dest) // Calls copySourceToDest from a *strings.Reader and a *bytes.Buffer
    if err != nil {
        t.FailNow()
    }

    got := dest.String()
    if got != input {
        t.Errorf("expected: %s, got: %s", input, got)
    }
}

In the example, source is a *strings.Reader, whereas dest is a *bytes.Buffer. Here, we test the behavior of copySourceToDest without creating any files.

While designing interfaces, the granularity(粒度) (how many methods the interface contains) is also something to keep in mind. A known proverb in Go relates to how big an interface should be:

Indeed, adding methods to an interface can decrease its level of reusability. io.Reader and io.Writer are powerful abstractions because they cannot get any simpler. Furthermore, we can also combine fine-grained interfaces to create higher-level abstractions. This is the case with io.ReadWriter, which combines the reader and writer behaviors:

type ReadWriter interface {
    Reader
    Writer
}

When to use interfaces

When should we create interfaces in Go? Let’s look at three concrete use cases where interfaces are usually considered to bring value. Note that the goal isn’t to be exhaustive(详尽无遗的) because the more cases we add, the more they would depend on the context. However, these three cases should give us a general idea:

Common behavior
Decoupling
Restricting behavior

Common behavior

The first option we will discuss is to use interfaces when multiple types implement a common behavior. In such a case, we can factor out the behavior inside an interface. If we look at the standard library, we can find many examples of such a use case. For example, sorting a collection can be factored out via three methods:

Retrieving the number of elements in the collection
Reporting whether one element must be sorted before another
Swapping two elements

Hence, the following interface was added to the sort package:

type Interface interface {
    Len() int // Number of elements
    Less(i, j int) bool // Checks two elements
    Swap(i, j int) // Swaps two elements
}

This interface has a strong potential for reusability because it encompasses the common behavior to sort any collection that is index-based.

Throughout the sort package, we can find dozens of implementations. If at some point we compute a collection of integers, for example, and we want to sort it, are we necessarily interested in the implementation type? Is it important whether the sorting algorithm is a merge sort or a quicksort? In many cases, we don’t care. Hence, the sorting behavior can be abstracted, and we can depend on the sort.Interface.

Finding the right abstraction to factor out a behavior can also bring many benefits. For example, the sort package provides utility functions that also rely on sort.Interface, such as checking whether a collection is already sorted. For instance:

func IsSorted(data Interface) bool {
    n := data.Len()
    for i := n - 1; i > 0; i-- {
        if data.Less(i, i-1) {
            return false
        }
    }
    return true
}

Because sort.Interface is the right level of abstraction, it makes it highly valuable.

Decoupling

Another important use case is about decoupling our code from an implementation. If we rely on an abstraction instead of a concrete implementation, the implementation itself can be replaced with another without even having to change our code. This is the Liskov Substitution Principle (the L in Robert C. Martin’s SOLID design principles).

SOLID

In object-oriented programming, SOLID is a mnemonic acronym for five principles intended to make source code more understandable, flexible, and maintainable. Although the principles apply to object-oriented programming, they can also form a core philosophy for methodologies such as agile software development and adaptive software development.

One benefit of decoupling can be related to unit testing. Let’s assume we want to implement a CreateNewCustomer method that creates a new customer and stores it. We decide to rely on the concrete implementation directly (let’s say a mysql.Store struct):

type CustomerService struct {
    store mysql.Store // Depends on the concrete implementation
}

func (cs CustomerService) CreateNewCustomer(id string) error {
    customer := Customer{id: id}
    return cs.store.StoreCustomer(customer)
}

Now, what if we want to test this method? Because customerService relies on the actual implementation to store a Customer, we are obliged to test it through integration tests, which requires spinning up a MySQL instance (unless we use an alternative technique such as go-sqlmock, but this isn’t the scope of this section). Although integration tests are helpful, that’s not always what we want to do. To give us more flexibility, we should decouple CustomerService from the actual implementation, which can be done via an interface like so:

type customerStorer interface { // Creates a storage abstraction
    StoreCustomer(Customer) error
}

type CustomerService struct {
    storer customerStorer // Decouples CustomerService from the actual implementation
}

func (cs CustomerService) CreateNewCustomer(id string) error {
    customer := Customer{id: id}
    return cs.storer.StoreCustomer(customer)
}

Because storing a customer is now done via an interface, this gives us more flexibility in how we want to test the method. For instance, we can:

Use the concrete implementation via integration tests
Use a mock (or any kind of test double) via unit tests
Or both

Restricting behavior

The last use case we will discuss can be pretty counterintuitive(违反常理的) at first sight. It’s about restricting a type to a specific behavior. Let’s imagine we implement a custom configuration package to deal with dynamic configuration. We create a specific container for int configurations via an IntConfig struct that also exposes two methods: Get and Set. Here’s how that code would look:

type IntConfig struct {
    // ...
}

func (c *IntConfig) Get() int {
    // Retrieve configuration
}

func (c *IntConfig) Set(value int) {
    // Update configuration
}

Now, suppose we receive an IntConfig that holds some specific configuration, such as a threshold. Yet, in our code, we are only interested in retrieving the configuration value, and we want to prevent updating it. How can we enforce that, semantically, this configuration is read-only, if we don’t want to change our configuration package? By creating an abstraction that restricts the behavior to retrieving only a config value:

type intConfigGetter interface {
    Get() int
}

Then, in our code, we can rely on intConfigGetter instead of the concrete implementation:

type Foo struct {
    threshold intConfigGetter
}

func NewFoo(threshold intConfigGetter) Foo { // Injects the configuration getter
    return Foo{threshold: threshold}
}

func (f Foo) Bar()  {
    threshold := f.threshold.Get() // Reads the configuration
    // ...
}

In this example, the configuration getter is injected into the NewFoo factory method. It doesn’t impact a client of this function because it can still pass an IntConfig struct as it implements intConfigGetter. Then, we can only read the configuration in the Bar method, not modify it. Therefore, we can also use interfaces to restrict a type to a specific behavior for various reasons, such as semantics enforcement.

Interface pollution

It’s fairly common to see interfaces being overused in Go projects. Perhaps the developer’s background was C# or Java, and they found it natural to create interfaces before concrete types. However, this isn’t how things should work in Go.

As we discussed, interfaces are made to create abstractions. And the main caveat(警告; 提醒) when programming meets abstractions is remembering that abstractions should be discovered, not created. What does this mean? It means we shouldn’t start creating abstractions in our code if there is no immediate reason to do so. We shouldn’t design with interfaces but wait for a concrete need. Said differently, we should create an interface when we need it, not when we foresee that we could need it.

In summary, we should be cautious when creating abstractions in our code—abstractions should be discovered, not created. It’s common for us, software developers, to overengineer our code by trying to guess what the perfect level of abstraction is, based on what we think we might need later. This process should be avoided because, in most cases, it pollutes our code with unnecessary abstractions, making it more complex to read.

Let’s not try to solve a problem abstractly but solve what has to be solved now. Last, but not least, if it’s unclear how an interface makes the code better, we should probably consider removing it to make our code simpler.

分析解释

核心定义与成因

接口污染的核心在于过度使用抽象。这通常发生在使用习惯了 C# 或 Java 等语言的开发者身上，他们习惯在编写具体类型之前先定义接口。在 Go 中，这种“预见性”的设计往往会导致代码中出现大量没有实际价值的间接层。

为什么这是一个问题？

增加复杂性：无用的间接层会干扰代码流，使阅读、理解和推理代码变得更加困难。
降低可读性：如果接口的用途不明确，调用者往往需要花费更多精力去寻找真正的实现逻辑。
性能开销：虽然在许多场景下微不足道，但通过接口调用方法需要在运行时进行哈希表查找以定位具体类型，这会带来一定的性能损耗。

Go 的核心哲学：发现而非创造

来源强调了一个关键原则：抽象应该是被发现的，而不是被创造的（Abstractions should be discovered, not created）。

开发者不应该为了“预见”未来可能的需求而提前创建接口。
只有当接口能让代码变得更好（例如提高可重用性或简化测试）时，才应该引入它。
Rob Pike 曾指出：“不要针对接口设计，要发现接口”。

什么时候不属于接口污染？

这些场景下接口能带来明确的价值：

共同行为（Common behavior）：当多个类型需要实现相同的逻辑（如标准库中的 sort.Interface 或 io.Reader）时，通过接口提取共性。
解耦（Decoupling）：为了让代码不依赖于具体的实现（例如数据库存储），从而方便进行单元测试（使用 Mock 对象）或在未来更换实现方案。
限制行为（Restricting behavior）：通过接口强制实施语义约束，例如将一个具有读写能力的结构体限制为只读。

总结建议

如果你发现很难解释某个接口存在的理由，或者直接调用具体实现会让代码更简洁，那么这个接口很可能就是“污染”。在 Go 中，建议先编写具体的实现，等到实际需要解耦或处理多种类型时再提取接口。

比喻理解

接口就像是翻译官。在只有两个说相同语言的人对话时，强制在中间塞进一个翻译官（接口）只会让沟通变慢且容易产生误解；只有当一个说中文的人需要和多个说不同外语的人（多种具体类型）交流，或者需要确保对话内容可以随时录音存档（测试解耦）时，翻译官的存在才有意义。

接口就像是一份合同。在生意还没开始做（没有实际业务逻辑）之前，就急着起草成百上千份细节详尽的合同（过度设计接口），只会让简单的买卖变得复杂无比。正确的做法是先开始交易（编写具体代码），当发现有多个合作伙伴都在做同样的事，或者需要规避某些风险时，再针对性地签一份简洁有效的合同（发现并提取接口）。

6. Interface on the producer side (生产者端接口)

TL;DR

Keeping interfaces on the client side avoids unnecessary abstractions.

Interfaces are satisfied implicitly in Go, which tends to be a gamechanger compared to languages with an explicit implementation. In most cases, the approach to follow is similar to what we described in the previous section: abstractions should be discovered, not created. This means that it’s not up to the producer to force a given abstraction for all the clients. Instead, it’s up to the client to decide whether it needs some form of abstraction and then determine the best abstraction level for its needs.

An interface should live on the consumer side in most cases. However, in particular contexts (for example, when we know—not foresee—that an abstraction will be helpful for consumers), we may want to have it on the producer side. If we do, we should strive to keep it as minimal as possible, increasing its reusability potential and making it more easily composable.

“生产者端接口” 这一话题讨论的是：接口应该由谁定义？是实现方（生产者），还是使用方（消费者）？Go 社区的最佳实践给出了明确答案：在绝大多数情况下，接口应该定义在使用方（消费者）的代码中。这与很多面向对象语言（如 Java、C#）的惯用法截然不同，其根源在于 Go 接口的隐式满足特性。

生产者端定义接口的问题：

如果生产者（例如一个 MySQLUserRepository 的实现包）自己定义了一个 IUserRepository 接口，然后让实现去满足它，这会导致：

不必要的耦合：生产者锁定了抽象层次，所有消费者都被迫使用这个可能包含他们不需要的方法的接口。
僵化的设计：接口难以演进，因为任何修改都可能破坏所有实现者和消费者。
过度设计：生产者容易设计出“大而全”的接口，因为它试图预测所有可能的用途。

消费者端定义接口的优势：

消费者（例如业务逻辑层）根据自己需要的方法来定义一个接口。

示例：

// 生产者包 (producer) - 提供具体实现
package db

type MySQLUserRepository struct { /* ... */ }

func (r *MySQLUserRepository) CreateUser(user User) error { /* ... */ }
func (r *MySQLUserRepository) GetUserByID(id int) (*User, error) { /* ... */ }
func (r *MySQLUserRepository) UpdateUser(user User) error { /* ... */ }
func (r *MySQLUserRepository) DeleteUser(id int) error { /* ... */ }
func (r *MySQLUserRepository) RunComplexAnalytics() (*Report, error) { /* ... */ } // 某个复杂方法

// 消费者包 (consumer) - 定义自己所需的接口
package service

// UserSaver 是消费者为自己定义的接口，只包含它真正需要的方法
type UserSaver interface {
    CreateUser(user User) error
}

func ProcessSignup(saver UserSaver, user User) error {
    // 这里只关心“保存”这个行为
    return saver.CreateUser(user)
}

// UserGetter 是另一个消费者定义的接口，用于不同的场景
type UserGetter interface {
    GetUserByID(id int) (*User, error)
}

func GetUserProfile(getter UserGetter, id int) (*User, error) {
    return getter.GetUserByID(id)
}

优势：

解耦与灵活：消费者 service 包完全不依赖生产者的具体类型（MySQLUserRepository），只依赖自己定义的小接口。这符合依赖倒置原则。
按需抽象：ProcessSignup 函数只需要一个能 CreateUser 的东西，它就定义这样一个极简接口。这避免了依赖不需要的方法（如 RunComplexAnalytics）。
易于测试：为 UserSaver 或 UserGetter 编写模拟测试非常容易。
组合自由：生产者 db.MySQLUserRepository 隐式地满足了这些接口，无需任何声明。未来可以轻松换用其他存储（如 PostgresUserRepository、MockRepository），只要它们实现了相应的方法。

何时放在生产者端？（例外情况）

原则总有例外。在以下情况下，由生产者定义接口是合理的：

提供通用、稳定的契约：当你提供的不是一个具体实现，而是一个被广泛认可、极简且稳定的行为契约时。标准库中的 io.Reader、io.Writer、error 接口就是典范。它们定义了计算机科学中的基础概念，几乎不会改变。
在包内部隐藏实现细节：在包内部使用接口来解耦具体实现，对外部消费者隐藏复杂结构。但这属于内部实现细节，对外暴露的通常仍是函数或结构体。
提供可选功能：例如 sql.Driver 接口，它定义了数据库驱动必须实现的方法，这是一个框架级的、由生产者（database/sql 包）定义的“插件”接口。

关键点：当你决定在生产者端定义接口时，务必遵循 “接口越小越好” 的原则。一个只包含1-3个方法的接口，远比一个20个方法的“全能”接口更有用、更持久、更容易组合。

7. Returning interfaces (返回接口)

TL;DR

To prevent being restricted in terms of flexibility, a function shouldn’t return interfaces but concrete implementations in most cases. Conversely, a function should accept interfaces whenever possible.

In most cases, we shouldn’t return interfaces but concrete implementations. Otherwise, it can make our design more complex due to package dependencies and can restrict flexibility because all the clients would have to rely on the same abstraction. Again, the conclusion is similar to the previous sections: if we know (not foresee) that an abstraction will be helpful for clients, we can consider returning an interface. Otherwise, we shouldn’t force abstractions; they should be discovered by clients. If a client needs to abstract an implementation for whatever reason, it can still do that on the client’s side.

函数应该返回具体类型，而不是接口类型。但函数应该尽可能接受接口作为参数。这个原则与”生产者端接口”的思想一脉相承，都是为了保持最大的灵活性和避免过早抽象。

这个原则的核心思想是：作为API提供者，不要替用户做决定。给他们具体的东西，让他们自己决定如何使用和抽象。

为什么不应该返回接口？

问题1：限制灵活性

当函数返回接口时，你强制所有调用者都使用相同的抽象。这意味着：

// ❌ 不推荐：返回接口
package db

type UserRepository interface {
    Create(user User) error
    Get(id int) (*User, error)
}

func NewUserRepository() UserRepository {
    return &MySQLRepository{}
}

// 所有调用者都必须使用 UserRepository 接口
// 即使他们可能有特殊需求

相比之下，返回具体类型：

// ✅ 推荐：返回具体类型
package db

func NewUserRepository() *MySQLRepository {
    return &MySQLRepository{}
}

type MySQLRepository struct { /* ... */ }

func (r *MySQLRepository) Create(user User) error { /* ... */ }
func (r *MySQLRepository) Get(id int) (*User, error) { /* ... */ }
func (r *MySQLRepository) SpecialMySQLFeature() { /* ... */ } // 具体类型的特有方法

优势：

调用者可以选择直接使用具体类型的所有功能
调用者也可以选择仅使用接口（如果需要抽象）
不会强制所有调用者使用相同的抽象级别

问题2：依赖方向问题

返回接口可能导致不合理的包依赖关系：

// ❌ 问题：返回接口导致消费者依赖生产者的抽象定义
// producer.go (生产者包)
package producer

type MyInterface interface {
    DoSomething()
}

func New() MyInterface {
    return &impl{}
}

// consumer.go (消费者包) - 必须导入 producer 包才能使用 MyInterface
package consumer

import "producer"

func Use() {
    obj := producer.New()  // 类型是 producer.MyInterface
    // 现在 consumer 依赖 producer 的接口定义
}

问题3：违背”发现抽象”原则

如果生产者返回接口，等于预先决定了抽象。但根据之前的原则，抽象应该由消费者在需要时自己发现和定义。

为什么应该接受接口作为参数？-> 提高通用性和可测试性

// ✅ 优秀实践：接受接口，返回具体类型
package processor

// 接受接口 - 提高函数通用性
func ProcessData(r io.Reader) error {
    // 可以接受文件、网络连接、内存缓冲区等
}

// 返回具体类型 - 给予调用者选择权
func NewProcessor() *ConcreteProcessor {
    return &ConcreteProcessor{}
}

何时可以返回接口？-> 在明确知道（而非预见）返回接口会带来实际好处的情况下

场景1：提供可选行为的场景

// 标准库的 error 接口是一个很好的例子
// error 是一个极简接口，有明确的契约
type error interface {
    Error() string
}

// 返回 error 接口是合理的，因为它定义了一个基本行为
func Parse(input string) (Result, error) {
    // 可能返回各种具体的 error 类型
    return result, &ParseError{...}
}

场景2：工厂模式或策略模式

// 当函数的作用是创建某种策略的实现时
type Logger interface {
    Log(message string)
}

// 根据配置返回不同的日志实现
func NewLogger(config Config) Logger {
    switch config.Type {
    case "file":
        return &FileLogger{...}
    case "console":
        return &ConsoleLogger{...}
    default:
        return &DefaultLogger{...}
    }
}

场景3：隐藏内部复杂的实现细节

// 当你不想暴露实现细节时
package cache

type Cache interface {
    Get(key string) ([]byte, error)
    Set(key string, value []byte) error
}

// New 返回接口，隐藏了具体是哪种缓存实现
func New() Cache {
    // 可能使用 Redis、内存或其他
    return createComplexCache()
}

8. any says nothing (滥用 any 类型)

TL;DR

Only use any if you need to accept or return any possible type, such as json.Marshal. Otherwise, any doesn’t provide meaningful information and can lead to compile-time issues by allowing a caller to call methods with any data type.

The any type can be helpful if there is a genuine need for accepting or returning any possible type (for instance, when it comes to marshaling or formatting). In general, we should avoid overgeneralizing the code we write at all costs. Perhaps a little bit of duplicated code might occasionally be better if it improves other aspects such as code expressiveness.

仅在真正需要接受或返回任意可能类型时才使用 any（例如 json.Marshal）。否则，any 不会提供有意义的信息，并可能因为允许调用者用任何数据类型调用方法而导致编译时问题。

在 Go 1.18+ 中，any 是空接口 interface{} 的类型别名：

type any = interface{}

这意味着 any 可以容纳任何类型的值，但这恰恰是它最大的危险所在。

package main

func main() {
	var i any

	i = 42
	i = "foo"
	i = struct {
		s string
	}{
		s: "bar",
	}
	i = f

	_ = i
}

func f() {}

关键要点：

any 意味着”没有任何类型信息”：使用它时，你放弃了编译时的类型检查
错误从编译时推迟到运行时：这违背了静态类型语言的优势
代码可读性下降：读者不知道函数接受什么类型的参数

优先选择其他方案：

具体类型（最明确）
接口（定义行为）
泛型（类型安全的抽象）

记住：少量的重复代码（如为不同类型写相似函数）通常比过度抽象的、使用 any 的代码更好，因为前者更清晰、更安全、更易维护。只有当真正需要处理任意类型时（如序列化、格式化等），才应使用 any。

为什么滥用 `any` 有害？

失去类型安全性（最严重的问题）

// ❌ 危险的示例
func Process(data any) {
    // 为了使用 data，我们需要类型断言
    // 但这在编译时无法检查
    str := data.(string)  // 如果 data 不是 string，运行时会 panic！
    fmt.Println(str)
}

func main() {
    Process("hello")      // 正常
    Process(42)           // 编译通过，但运行时会 panic！
    Process([]int{1,2,3}) // 编译通过，但运行时会 panic！
}

代码意图不清晰

// ❌ 不清晰：这个函数到底接受什么？
func Store(key string, value any) error {
    // 什么类型的 value 是合法的？
}

// ✅ 清晰：明确说明接受什么
func StoreString(key string, value string) error
func StoreInt(key string, value int) error
func StoreUser(key string, value User) error

推迟错误到运行时

类型错误应该在编译时捕获，而不是运行时：

// ❌ 错误在运行时才发现
func Calculate(a, b any) any {
    return a.(int) + b.(int)  // 假设是 int，但不保证
}

// 编译通过，但...
Calculate(10, 20)     // 正常：返回 30
Calculate(10, "20")   // 编译通过，但运行时会 panic！
Calculate("10", 20)   // 编译通过，但运行时会 panic！

// ✅ 更好的方式：使用泛型（Go 1.18+）
func Calculate[T int | float64](a, b T) T {
    return a + b  // 类型安全，编译时检查
}

何时应该使用 any？

处理未知结构的 JSON 数据

// 这是合理的，因为 JSON 可以是任何结构
func ParseJSON(data []byte) (map[string]any, error) {
    var result map[string]any
    if err := json.Unmarshal(data, &result); err != nil {
        return nil, err
    }
    return result, nil
}

容器数据结构

// 当实现通用容器时（尽管泛型通常是更好的选择）
type Stack struct {
    items []any
}

func (s *Stack) Push(item any) {
    s.items = append(s.items, item)
}

// 但更好的做法是使用泛型：
type Stack[T any] struct {
    items []T
}

格式化和日志

// fmt 包正确使用 any
func Printf(format string, args ...any) (n int, err error)

// 日志记录通常接受 any
log.Printf("User %v logged in at %v", userID, timestamp)

标准库中的合理使用

// encoding/json
func Marshal(v any) ([]byte, error)

// fmt
func Sprintf(format string, a ...any) string

// context
func WithValue(parent Context, key, val any) Context

使用 any 的安全模式

如果必须使用 any，请遵循这些安全模式：

立即进行类型检查

func SafeProcess(value any) error {
    switch v := value.(type) {
    case string:
        return processString(v)
    case int:
        return processInt(v)
    case []byte:
        return processBytes(v)
    default:
        return fmt.Errorf("unsupported type: %T", value)
    }
}

使用类型断言的安全形式

func GetString(value any) (string, bool) {
    str, ok := value.(string)  // 安全断言，不会 panic
    return str, ok
}

func main() {
    if str, ok := GetString(someValue); ok {
        // 安全地使用 str
    } else {
        // 处理类型不匹配
    }
}

约束 any 的使用范围

// 内部使用 any，但对外暴露类型安全的接口
type Processor struct{}

func (p *Processor) processInternal(data any) {
    // 内部处理，假设调用者知道规则
}

// 公开的类型安全方法
func (p *Processor) ProcessString(s string) {
    p.processInternal(s)
}

func (p *Processor) ProcessInt(i int) {
    p.processInternal(i)
}

替代方案：使用泛型（Go 1.18+）

大多数滥用 any 的场景都可以用泛型更好地解决：

// ❌ 使用 any
func FindInSlice(slice []any, target any) int {
    for i, v := range slice {
        if v == target {  // 比较可能不如预期
            return i
        }
    }
    return -1
}

// ✅ 使用泛型
func FindInSlice[T comparable](slice []T, target T) int {
    for i, v := range slice {
        if v == target {  // 类型安全的比较
            return i
        }
    }
    return -1
}

// 使用
FindInSlice([]string{"a", "b", "c"}, "b")  // 正确
FindInSlice([]int{1, 2, 3}, 2)             // 正确
// FindInSlice([]string{"a", "b"}, 123)    // 编译错误：类型不匹配

9. Being confused about when to use generics (泛型使用不当)

TL;DR

Relying on generics and type parameters can prevent writing boilerplate code to factor out elements or behaviors. However, do not use type parameters prematurely, but only when you see a concrete need for them. Otherwise, they introduce unnecessary abstractions and complexity.

More: Being confused about when to use generics

核心观点：依赖泛型和类型参数可以避免编写提取元素或行为的样板代码。但是，不要过早使用类型参数，只有在看到具体需要时才使用它们。否则，它们会引入不必要的抽象和复杂性。

package main

import (
	"fmt"
	"sort"
)

func getKeys(m any) ([]any, error) {
	switch t := m.(type) {
	default:
		return nil, fmt.Errorf("unknown type: %T", t)
	case map[string]int:
		var keys []any
		for k := range t {
			keys = append(keys, k)
		}
		return keys, nil
	case map[int]string:
		// ...
	}

	return nil, nil
}

func getKeysGenerics[K comparable, V any](m map[K]V) []K {
	var keys []K
	for k := range m {
		keys = append(keys, k)
	}
	return keys
}

type customConstraint interface {
	~int | ~string
}

func getKeysWithConstraint[K customConstraint, V any](m map[K]V) []K {
	return nil
}

type Node[T any] struct {
	Val  T
	next *Node[T]
}

func (n *Node[T]) Add(next *Node[T]) {
	n.next = next
}

type SliceFn[T any] struct {
	S       []T
	Compare func(T, T) bool
}

func (s SliceFn[T]) Len() int           { return len(s.S) }
func (s SliceFn[T]) Less(i, j int) bool { return s.Compare(s.S[i], s.S[j]) }
func (s SliceFn[T]) Swap(i, j int)      { s.S[i], s.S[j] = s.S[j], s.S[i] }

func main() {
	s := SliceFn[int]{
		S: []int{3, 2, 1},
		Compare: func(a, b int) bool {
			return a < b
		},
	}
	sort.Sort(s)
	fmt.Println(s.S)
}

10. Not being aware of the possible problems with type embedding (类型嵌入风险)

TL;DR

Using type embedding can also help avoid boilerplate code; however, ensure that doing so doesn’t lead to visibility issues where some fields should have remained hidden.

核心观点：使用类型嵌入可以帮助避免样板代码，但要确保这样做不会导致可见性问题，即某些本应保持隐藏的字段被意外暴露。

When creating a struct, Go offers the option to embed types. But this can sometimes lead to unexpected behaviors if we don’t understand all the implications of type embedding. Throughout this section, we look at how to embed types, what these bring, and the possible issues.

In Go, a struct field is called embedded if it’s declared without a name. For example,

type Foo struct {
    Bar // Embedded field
}

type Bar struct {
    Baz int
}

In the Foo struct, the Bar type is declared without an associated name; hence, it’s an embedded field.

We use embedding to promote the fields and methods of an embedded type. Because Bar contains a Baz field, this field is promoted to Foo. Therefore, Baz becomes available from Foo.

What can we say about type embedding? First, let’s note that it’s rarely a necessity, and it means that whatever the use case, we can probably solve it as well without type embedding. Type embedding is mainly used for convenience: in most cases, to promote behaviors.

If we decide to use type embedding, we need to keep two main constraints in mind:

It shouldn’t be used solely as some syntactic sugar to simplify accessing a field (such as Foo.Baz() instead of Foo.Bar.Baz()). If this is the only rationale, let’s not embed the inner type and use a field instead.
It shouldn’t promote data (fields) or a behavior (methods) we want to hide from the outside: for example, if it allows clients to access a locking behavior that should remain private to the struct.

Using type embedding consciously by keeping these constraints in mind can help avoid boilerplate code with additional forwarding methods. However, let’s make sure we don’t do it solely for cosmetics and not promote elements that should remain hidden.

示例代码：

package main

import (
	"io"
	"os"
	"sync"
)

type Foo struct {
	Bar
}

type Bar struct {
	Baz int
}

func fooBar() {
	foo := Foo{}
	foo.Baz = 42
}

type InMem struct {
	sync.Mutex
	m map[string]int
}

func New() *InMem {
	return &InMem{m: make(map[string]int)}
}

func (i *InMem) Get(key string) (int, bool) {
	i.Lock()
	v, contains := i.m[key]
	i.Unlock()
	return v, contains
}

type Logger struct {
	writeCloser io.WriteCloser
}

func (l Logger) Write(p []byte) (int, error) {
	return l.writeCloser.Write(p)
}

func (l Logger) Close() error {
	return l.writeCloser.Close()
}

func main() {
	l := Logger{writeCloser: os.Stdout}
	_, _ = l.Write([]byte("foo"))
	_ = l.Close()
}

什么是类型嵌入？

类型嵌入是 Go 中结构体字段的一种特殊声明方式，字段没有名称，只有类型：

type Foo struct {
    Bar  // 嵌入字段，没有字段名，只有类型
}

type Bar struct {
    Baz int
}

在 Foo 结构体中，Bar 类型被嵌入，因此 Bar 的字段和方法会被”提升”到 Foo 中，可以直接通过 Foo 访问。

类型嵌入的主要用途

(1) 方法提升：嵌入类型的方法会被提升到外层类型，可以避免编写转发方法

type Reader interface {
    Read(p []byte) (n int, err error)
}

type File struct {
    *os.File  // 嵌入，File 现在有了 Read 方法
}

// 无需编写转发方法：
// func (f File) Read(p []byte) (n int, err error) {
//     return f.File.Read(p)
// }

(2) 接口实现：通过嵌入，外层类型自动实现了内层类型实现的接口

type MyReader struct {
    io.Reader  // 嵌入，MyReader 自动实现了 io.Reader 接口
}

类型嵌入的潜在问题

(1) 意外暴露私有字段和方法

// 问题示例：意外暴露内部实现
type Account struct {
    sync.Mutex  // 嵌入锁
    balance float64
}

func main() {
    acc := Account{}
    acc.Lock()    // ⚠️ 问题：外部可以直接调用锁的方法
    acc.Unlock()  // 这破坏了封装性
}

问题：sync.Mutex 的 Lock() 和 Unlock() 方法被提升到 Account，外部代码可以直接控制锁，可能导致：死锁风险，锁状态管理混乱，破坏了数据封装的完整性。

(2) 命名冲突和歧义

type A struct{}

func (A) Process() { fmt.Println("A.Process") }

type B struct{}

func (B) Process() { fmt.Println("B.Process") }

type C struct {
    A
    B
}

func main() {
    c := C{}
    // c.Process()  // ⚠️ 编译错误：ambiguous selector c.Process
    // 必须明确指定：
    c.A.Process()  // 正确
    c.B.Process()  // 正确
}

(3) 接口实现冲突

type Writer interface {
    Write(data []byte) error
}

type FileWriter struct {
    Writer  // 嵌入接口
}

// 问题：FileWriter 没有实现 Write 方法
// 但在编译时不会报错，直到运行时才可能发现

(4) 过度提升导致 API 污染

type Config struct {
    // 嵌入过多的类型可能导致 API 过于复杂
    DatabaseConfig
    CacheConfig
    APIConfig
    LoggingConfig
    // 所有嵌入类型的公共方法都会被提升
}

// 使用 Config 时，会有大量方法可用，但很多可能是不相关的

使用类型嵌入的最佳实践

(1) 仅在需要行为提升时使用

// ✅ 正确：需要提升 io.Reader 的行为
type BufferedReader struct {
    io.Reader  // 嵌入，为了获得 Read 方法
    buffer []byte
}

// ❌ 错误：仅仅为了语法糖
type User struct {
    Address  // 嵌入，只是为了能写 user.City 而不是 user.Address.City
}

// ✅ 更好：使用命名字段
type User struct {
    addr Address  // 命名字段，访问需要 user.addr.City
}

(2) 不要嵌入应该隐藏的类型

// ❌ 错误：暴露内部同步机制
type SafeCounter struct {
    sync.Mutex
    count int
}

// ✅ 正确：将锁作为私有字段
type SafeCounter struct {
    mu    sync.Mutex  // 私有字段，不暴露 Mutex 的方法
    count int
}

func (sc *SafeCounter) Increment() {
    sc.mu.Lock()
    defer sc.mu.Unlock()
    sc.count++
}

(3) 优先组合而非继承思维

// Go 鼓励组合而非继承
type Server struct {
    // 明确组合各个组件
    httpServer *http.Server
    router     *mux.Router
    logger     *log.Logger
}

// 而不是：
type Server struct {
    *http.Server  // 嵌入可能导致不必要的方法提升
    *mux.Router
    *log.Logger
}

(4) 谨慎处理接口嵌入

// ✅ 正确使用接口嵌入
type ReadWriter interface {
    io.Reader
    io.Writer
}

// 小心：确保类型确实实现了接口
type MyType struct {
    io.Writer  // 嵌入接口
}

func NewMyType(w io.Writer) *MyType {
    return &MyType{Writer: w}  // 确保传入的 w 不为 nil
}

记住：类型嵌入是工具，不是必需品。在 Go 中，几乎总能通过不使用类型嵌入来解决问题。只有当它真正简化了代码且不会导致可见性问题时，才应该使用它。

11. Not using the functional options pattern (缺少函数选项模式)

TL;DR

To handle options conveniently and in an API-friendly manner, use the functional options pattern.

核心观点：为了以方便且 API 友好的方式处理选项，请使用函数选项模式。这是一种优雅处理可选参数和配置的方法。

Although there are different implementations with minor variations, the main idea is as follows:

An unexported struct holds the configuration: options.
Each option is a function that returns the same type: type Option func(options *options) error. For example, WithPort accepts an int argument that represents the port and returns an Option type that represents how to update the options struct.

type options struct {
  port *int
}

type Option func(options *options) error

func WithPort(port int) Option {
  return func(options *options) error {
    if port < 0 {
      return errors.New("port should be positive")
    }
    options.port = &port
    return nil
  }
}

func NewServer(addr string, opts ...Option) ( *http.Server, error) {
  var options options
  for _, opt := range opts {
    err := opt(&options)
    if err != nil {
      return nil, err
    }
  }

  // At this stage, the options struct is built and contains the config
  // Therefore, we can implement our logic related to port configuration
  var port int
  if options.port == nil {
    port = defaultHTTPPort
  } else {
    if *options.port == 0 {
      port = randomPort()
    } else {
      port = *options.port
    }
  }

  // ...
}

The functional options pattern provides a handy and API-friendly way to handle options. Although the builder pattern can be a valid option, it has some minor downsides (having to pass a config struct that can be empty or a less handy way to handle error management) that tend to make the functional options pattern the idiomatic way to deal with these kind of problems in Go.

为什么需要函数选项模式？

在 Go 中，函数通常有多个配置选项，传统的解决方法有以下问题：

(1) 配置结构体问题

// ❌ 问题：需要传入完整配置结构体，即使很多字段是默认值
type Config struct {
    Port    int
    Timeout time.Duration
    Logger  Logger
    // ... 更多字段
}

func NewServer(addr string, cfg Config) *Server {
    // 即使只需要设置 Port，也要创建完整 Config
}

// 使用：
server := NewServer(":8080", Config{
    Port:    8080,
    Timeout: 30 * time.Second,  // 必须指定默认值
    Logger:  nil,               // 必须明确传递 nil
})

(2) 多参数问题

// ❌ 问题：参数太多，难以记忆和维护
func NewServer(addr string, port int, timeout time.Duration,
               logger Logger, maxConns int, tlsConfig *tls.Config) *Server {
    // 参数顺序重要，且必须传递所有参数
}

(3) 变长参数使用基础类型

// ❌ 问题：类型不安全，可读性差
func NewServer(addr string, opts ...interface{}) *Server {
    // 需要类型断言，容易出错
}

函数选项模式解决方案

基本结构

// 1. 非导出配置结构体
type options struct {
    port     *int
    timeout  time.Duration
    logger   Logger
    maxConns int
}

// 2. Option 函数类型
type Option func(*options) error

// 3. 选项构造函数（通常以 With 开头）
func WithPort(port int) Option {
    return func(o *options) error {
        if port < 0 || port > 65535 {
            return errors.New("invalid port")
        }
        o.port = &port
        return nil
    }
}

func WithTimeout(timeout time.Duration) Option {
    return func(o *options) error {
        if timeout < 0 {
            return errors.New("timeout must be positive")
        }
        o.timeout = timeout
        return nil
    }
}

func WithLogger(logger Logger) Option {
    return func(o *options) error {
        if logger == nil {
            return errors.New("logger cannot be nil")
        }
        o.logger = logger
        return nil
    }
}

// 4. 构造函数使用可变参数接受选项
func NewServer(addr string, opts ...Option) (*Server, error) {
    // 设置默认值
    config := options{
        port:     nil,           // 使用指针表示可选
        timeout:  30 * time.Second,
        logger:   defaultLogger,
        maxConns: 100,
    }

    // 应用所有选项
    for _, opt := range opts {
        if err := opt(&config); err != nil {
            return nil, fmt.Errorf("applying option: %w", err)
        }
    }

    // 最终配置处理
    var port int
    if config.port == nil {
        port = defaultPort
    } else {
        port = *config.port
    }

    // 创建并返回 Server
    return &Server{
        addr:    addr,
        port:    port,
        timeout: config.timeout,
        logger:  config.logger,
    }, nil
}

使用示例

// 只设置需要的选项，顺序无关
server1, err := NewServer("localhost")

server2, err := NewServer("localhost",
    WithPort(8080),
    WithTimeout(60*time.Second),
)

server3, err := NewServer("localhost",
    WithLogger(customLogger),
    WithPort(9000),
)

函数选项模式是 Go 社区广泛接受的配置模式，特别是在标准库和流行开源项目中常见。它提供了优秀的 API 体验，同时保持了代码的简洁和可维护性。

12. Project misorganization (project structure and package organization) (项目结构与包名管理)

Regarding the overall organization, there are different schools of thought. For example, should we organize our application by context or by layer? It depends on our preferences. We may favor grouping code per context (such as the customer context, the contract context, etc.), or we may favor following hexagonal(六边形的) architecture principles and group per technical layer. If the decision we make fits our use case, it cannot be a wrong decision, as long as we remain consistent with it.

Regarding packages, there are multiple best practices that we should follow. First, we should avoid premature packaging because it might cause us to overcomplicate a project. Sometimes, it’s better to use a simple organization and have our project evolve when we understand what it contains rather than forcing ourselves to make the perfect structure up front. Granularity is another essential thing to consider. We should avoid having dozens of nano packages containing only one or two files. If we do, it’s because we have probably missed some logical connections across these packages, making our project harder for readers to understand. Conversely, we should also avoid huge packages that dilute the meaning of a package name.

Package naming should also be considered with care. As we all know (as developers), naming is hard. To help clients understand a Go project, we should name our packages after what they provide, not what they contain. Also, naming should be meaningful. Therefore, a package name should be short, concise, expressive, and, by convention, a single lowercase word.

Regarding what to export, the rule is pretty straightforward. We should minimize what should be exported as much as possible to reduce the coupling between packages and keep unnecessary exported elements hidden. If we are unsure whether to export an element or not, we should default to not exporting it. Later, if we discover that we need to export it, we can adjust our code. Let’s also keep in mind some exceptions, such as making fields exported so that a struct can be unmarshaled with encoding/json.

Organizing a project isn’t straightforward, but following these rules should help make it easier to maintain. However, remember that consistency is also vital to ease maintainability. Therefore, let’s make sure that we keep things as consistent as possible within a codebase.

Note: In 2023, the Go team has published an official guideline for organizing / structuring a Go project: go.dev/doc/modules/layout

核心观点：项目组织没有单一标准答案，但遵循一些最佳实践可以使代码更易维护。关键在于保持一致性，选择适合团队和项目的方式。

项目结构组织方式

按业务上下文组织 vs 按技术层组织

建议：没有绝对正确，选择后保持一致性。Go社区倾向于按业务上下文组织。

按业务上下文（领域驱动）

project/
  customer/          # 客户上下文
    handler.go
    service.go
    repository.go
    model.go
  order/             # 订单上下文
    handler.go
    service.go
    repository.go
    model.go
  product/           # 产品上下文
    handler.go
    service.go
    repository.go
    model.go

优点：

高内聚：相关业务逻辑集中在一起
易于维护：修改某个功能时只需关注单个目录
符合微服务趋势：便于未来拆分为独立服务

按技术层（分层架构）

project/
  handlers/          # 控制层
    customer_handler.go
    order_handler.go
    product_handler.go
  services/          # 业务逻辑层
    customer_service.go
    order_service.go
    product_service.go
  repositories/      # 数据访问层
    customer_repo.go
    order_repo.go
    product_repo.go
  models/            # 数据模型
    customer.go
    order.go
    product.go

优点：

关注点分离：每层有明确职责
技术栈统一：同类技术放在一起
传统模式：许多团队熟悉此模式

包组织最佳实践

(1) 避免过早分包

原则：让项目自然演进，不要一开始就设计复杂结构。

// 初期：从简单开始
project/
  main.go          # 包含所有逻辑
  utils.go         # 辅助函数

// 中期：按需拆分
project/
  cmd/
    server/
      main.go      # 入口
  internal/
    api/           # API相关
    db/            # 数据库操作
    models/        # 数据模型

// 成熟期：精细组织
project/
  cmd/
    server/
      main.go
  internal/
    user/          # 用户模块
    order/         # 订单模块
    product/       # 产品模块
  pkg/
    utils/         # 可复用的工具
    config/        # 配置管理

(2) 包的粒度要适中

// ❌ 过于细粒度（纳米包）
project/
  pkg/
    stringutil/    # 仅包含2-3个字符串函数
    intutil/       # 仅包含2-3个整数函数
    timeutil/      # 仅包含2-3个时间函数

// ❌ 过于粗粒度（巨型包）
project/
  pkg/
    utils/         # 包含数百个不相关的函数
                   # 名称失去意义

// ✅ 适度粒度
project/
  pkg/
    strutil/       # 字符串相关工具
    mathutil/      # 数学计算工具
    timeutil/      # 时间日期工具（包含相关功能）

(3) 包命名要明确

// ❌ 糟糕的命名
common/         # 太泛，不知道提供什么
util/           # 不知道具体用途
helper/         # 不清楚帮助什么
misc/           # 杂物堆

// ✅ 好的命名
validator/      # 提供验证功能
formatter/      # 提供格式化功能
authenticator/  # 提供认证功能
cache/          # 提供缓存功能

// 规则：
// 1. 使用单数名词：user 而不是 users
// 2. 简短但描述性：log 而不是 loggingfacility
// 3. 避免缩写：strconv（允许） vs stcv（避免）

(4) 最小化导出

导出原则：

默认不导出，需要时再公开
只导出必要的接口和函数
内部实现保持私有

// 内部包结构
package cache

// 导出必须的接口
type Cache interface {
    Get(key string) ([]byte, error)
    Set(key string, value []byte) error
}

// 不导出具体实现
type redisCache struct {
    client *redis.Client
}

// 导出工厂函数
func NewRedisCache(addr string) (Cache, error) {
    return &redisCache{
        client: connectRedis(addr),
    }, nil
}

// 不导出的辅助函数
func connectRedis(addr string) *redis.Client {
    // 内部实现细节
}

(5) 处理 JSON 序列化等特殊情况

type User struct {
    // 字段必须导出才能被 encoding/json 访问
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email,omitempty"`

    // 不导出的字段不会被序列化
    passwordHash string
}

项目结构模板示例

标准 Go 项目布局（参考）

myproject/
├── cmd/                  # 可执行程序入口
│   ├── myapp/
│   │   └── main.go       # 主程序
│   └── mytool/
│       └── main.go       # 工具程序
├── internal/             # 私有应用代码
│   ├── api/              # API 层
│   ├── service/          # 业务逻辑层
│   ├── repository/       # 数据访问层
│   └── model/            # 数据模型
├── pkg/                  # 可公开导入的库代码
│   ├── libfoo/           # 库包 A
│   └── libbar/           # 库包 B
├── api/                  # API 定义（protobuf, OpenAPI）
├── web/                  # Web 资源
├── configs/              # 配置文件
├── init/                 # 初始化脚本
├── scripts/              # 构建/部署脚本
├── build/                # 构建输出
├── deployments/          # 部署配置
├── test/                 # 测试数据
├── docs/                 # 文档
├── tools/                # 开发工具
├── examples/             # 示例代码
├── vendor/               # 依赖（可选）
├── go.mod
├── go.sum
└── README.md

微服务项目结构

microservice/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/          # HTTP/gRPC 处理器
│   ├── service/          # 业务逻辑实现
│   ├── repository/       # 数据持久化
│   ├── domain/           # 领域模型
│   ├── middleware/       # 中间件
│   └── config/           # 配置读取
├── pkg/
│   ├── logger/           # 日志组件
│   ├── database/         # 数据库封装
│   └── validator/        # 验证器
├── api/
│   └── v1/               # API 协议定义
├── deployments/
│   ├── docker/
│   └── kubernetes/
├── migrations/           # 数据库迁移
├── scripts/              # 脚本
└── tests/                # 测试

关键实践总结

Do’s（应该做的）

从简单开始：开始时用扁平结构，需要时再重构
保持一致性：选定模式后，整个项目保持一致
合理命名：包名描述功能，而不是内容
最小化公开 API：只导出必要的部分
考虑可读性：让新成员能快速理解结构

Don’ts（不应该做的）

不要过度设计：避免过早优化项目结构
不要创建太多小包：避免”纳米包”综合症
不要使用无意义的包名：如 common、utils
不要随意导出：默认私有，需要时再公开
不要忽略团队约定：遵循团队已有的模式

决策指南

当不确定如何组织时，问这些问题：

项目规模：小型项目用简单结构，大型项目需要更细致的组织
团队规模：大团队需要更规范的结构，小团队可以更灵活
部署方式：单体应用 vs 微服务影响结构选择
维护周期：长期维护的项目需要更稳健的结构
外部依赖：是否作为库供他人使用？

最后记住：没有完美的结构，只有适合当前项目的结构。随着项目演进，结构也需要调整。重要的是保持代码清晰、可维护，并让团队成员都能理解和遵循。

13. Creating utility packages (避免使用通用、无意义的包名)

TL;DR

Naming is a critical piece of application design. Creating packages such as common, util, and shared doesn’t bring much value for the reader. Refactor such packages into meaningful and specific package names.

Also, bear in mind that naming a package after what it provides and not what it contains can be an efficient way to increase its expressiveness.

核心观点：避免使用通用、无意义的包名（如 common, util, shared），而应使用具体、有意义的名称。

这条建议的本质是：通过有目的性的包命名来驱动更好的软件设计。它强迫你思考每个类的单一职责和逻辑归属，从而产生更模块化、更易于理解和更健壮的代码结构。拒绝“杂物抽屉”，拥抱“精心整理的工具箱”。

为什么 util、common 这类包名不好？

成为“杂物抽屉”
- 像 utils 或 common 这样的包，很容易变成一个什么都可以往里扔的“万能包”。随着项目增长，它会包含各种不相关的类：日期处理、字符串工具、加密助手、日志格式化、DTO 对象等等。
- 这违反了高内聚、低耦合的原则。包内的类之间几乎没有逻辑关联。
对读者毫无价值
- 当你看到一个导入语句是 from com.example.util import StringHelper 时，util 这个词没有传达任何关于 StringHelper 功能、所属领域或依赖关系的有效信息。
- 开发者必须深入查看代码才能理解这个类的用途和上下文。
隐藏设计缺陷
- 将一些类随意放入 util，可能会掩盖它们在领域模型中的正确位置。例如，一个 OrderValidator 本应属于 order 领域包，却被错误地放入了 common.validation 中，割裂了其与业务逻辑的联系。

解决方案：创建有意义的包

原则是：以包“提供什么”或“属于哪个领域”来命名，而不是以它“包含什么杂项”来命名。

按功能/提供的能力分组

将“杂物抽屉”拆分成多个目的明确的小包。

反面例子：

com.company.util -> 包含 DateUtil, FileUtil, HttpUtil, EncryptionUtil

正面重构：这样，从包名就能立刻知道其核心职责

com.company.**time**.DateParser (专注于时间相关)

com.company.**io**.FileReader (专注于输入输出)

com.company.**http**.client.HttpClient (专注于HTTP通信)

com.company.**security**.encryption.Encryptor (专注于安全)

按领域/模块分组

将工具类划分到它们所服务的特定业务领域或模块中。

反面例子：

com.company.common -> 包含 OrderHelper, UserDto, ConfigConstants

正面重构：这强化了领域边界，让代码与业务结构对齐

com.company.**order**.domain.OrderIdGenerator (属于order领域)

com.company.**user**.dto.UserResponse (属于user领域)

com.company.**configuration**.AppConfig (属于配置领域)

平衡与例外

当然，在非常小的项目或原型中，一个 utils 包可能无可厚非。但一旦项目开始增长，遵循这一原则将极大地提升代码的可读性、可维护性和架构清晰度。

14. Ignoring package name collisions (变量名与包名发生冲突)

TL;DR

To avoid naming collisions between variables and packages, leading to confusion or perhaps even bugs, use unique names for each one. If this isn’t feasible, use an import alias to change the qualifier to differentiate the package name from the variable name, or think of a better name.

Package collisions occur when a variable name collides with an existing package name, preventing the package from being reused. We should prevent variable name collisions to avoid ambiguity. If we face a collision, we should either find another meaningful name or use an import alias.

核心问题：在 Go 中，当变量名、函数名或其他标识符与包名发生冲突时，会导致编译错误或混淆。特别是在使用包别名时，需要特别注意命名冲突。

包导入与局部变量冲突

package main

import "fmt"

func main() {
    // 问题：变量名与包名相同
    fmt := "some string"  // 这会覆盖 fmt 包的作用域
    fmt.Println("Hello")  // 编译错误：fmt.Println 未定义（现在 fmt 是字符串）
}

多包同名冲突

package main

import (
    "github.com/user/config"  // 第三方 config 包
    "myproject/config"        // 本地 config 包 - 冲突！
)

func main() {
    // 两个包都叫 config，无法同时导入
}

包别名与标识符冲突

package main

import (
    json "encoding/json"  // 包别名
    "fmt"
)

func main() {
    json := "some data"  // 变量名与包别名冲突
    // 现在无法使用 json 包
}

解决方案：使用包别名

package main

import (
    "fmt"
    myConfig "github.com/user/config"  // 为第三方包设置别名
    localConfig "myproject/config"     // 为本地包设置别名
)

func main() {
    fmt := "formatted string"  // 局部变量

    // 使用别名访问包
    config := myConfig.Load()
    localCfg := localConfig.Default()
}

在 Go 中处理包名冲突，优先使用有意义的包别名，其次考虑重命名局部标识符。Go 的静态类型系统和严格的导入规则使得提前发现和解决命名冲突变得更加重要。遵循”显式优于隐式”的原则，使用清晰的别名可以显著提高代码的可读性和可维护性。

15. Missing code documentation (缺少代码文档)

TL;DR

To help clients and maintainers understand your code’s purpose, document exported elements.

Documentation is an important aspect of coding. It simplifies how clients can consume an API but can also help in maintaining a project. In Go, we should follow some rules to make our code idiomatic:

First, every exported element must be documented. Whether it is a structure, an interface, a function, or something else, if it’s exported, it must be documented. The convention is to add comments, starting with the name of the exported element.

As a convention, each comment should be a complete sentence that ends with punctuation. Also bear in mind that when we document a function (or a method), we should highlight what the function intends to do, not how it does it; this belongs to the core of a function and comments, not documentation. Furthermore, the documentation should ideally provide enough information that the consumer does not have to look at our code to understand how to use an exported element.

When it comes to documenting a variable or a constant, we might be interested in conveying two aspects: its purpose and its content. The former should live as code documentation to be useful for external clients. The latter, though, shouldn’t necessarily be public.

To help clients and maintainers understand a package’s scope, we should also document each package. The convention is to start the comment with // Package followed by the package name. The first line of a package comment should be concise. That’s because it will appear in the package. Then, we can provide all the information we need in the following lines.

Documenting our code shouldn’t be a constraint. We should take the opportunity to make sure it helps clients and maintainers to understand the purpose of our code.

核心原则：所有导出的元素都必须有文档。Go 语言通过文档注释（doc comments）来生成官方文档，这是 Go 生态系统的核心组成部分。

必须文档化的内容

(1) 包级文档（Package Documentation）

每个包都必须有包级文档，通常放在包声明的上方：

// Package httputil provides HTTP utility functions, complementing the
// more common ones in the net/http package.
//
// This package includes:
// - Request/response debugging helpers
// - HTTP client utilities
// - Common middleware components
package httputil

规范要求：

第一行以 Package <包名> 开头
第一行简洁描述包的核心功能
后续行提供更详细的信息
显示在 go doc 和 pkg.go.dev 上

(2) 导出函数/方法文档

// ValidateUser checks if the provided user meets all business requirements.
// It validates the user's email format, password strength, and required fields.
// Returns nil if validation passes, or ValidationError if any check fails.
//
// Example:
//  err := ValidateUser(user)
//  if err != nil {
//      return err
//  }
func ValidateUser(user User) error {
    // 实现细节
}

规范要求：

描述”做什么”，不是”怎么做” - 重点在意图而非实现
使用完整句子，以句号结尾
提供使用示例（如果复杂）
说明参数、返回值、错误情况

(3) 导出类型/结构体文档

// Config holds application configuration settings.
// This struct is safe for concurrent use after initialization.
type Config struct {
    // Host is the server hostname or IP address.
    Host string `json:"host"`

    // Port is the server port number (default: 8080).
    Port int `json:"port"`

    // Timeout is the request timeout in seconds.
    Timeout int `json:"timeout"`
}

(4) 导出变量/常量文档

// DefaultPort is the default HTTP port used when none is specified.
const DefaultPort = 8080

// ErrInvalidInput is returned when user input fails validation.
var ErrInvalidInput = errors.New("invalid input")

Go 文档的独特优势

工具链深度集成

# 查看包文档
go doc net/http

# 查看特定函数
go doc fmt.Printf

# 启动本地文档服务器
godoc -http=:6060

文档生成工具链

(1) 标准工具

# 格式化文档注释
go fmt ./...

# 检查文档完整性
go vet ./...

# 专门的文档检查工具
golang.org/x/tools/go/analysis/passes/doc

(2) 生成 HTML 文档

# 生成包文档网站
godoc -url /pkg/your-package > docs.html

# 使用pkgsite（Go 1.16+）
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite

为什么 Go 特别强调文档

Go 文档是公开 API 契约：pkg.go.dev 自动为所有公共包生成文档
文档驱动开发文化：Go 社区优先考虑清晰、简洁的 API 文档
工具链强制执行：go vet 会检查缺失的文档
文档影响包的可发现性：良好的文档提高包的采用率

在 Go 中，文档不是可选的附加品，而是代码的核心组成部分。良好的文档：

减少使用成本：用户无需阅读源代码
提高维护性：清晰的意图说明
增强可靠性：示例即测试
促进代码重用：清晰的API契约
遵循”文档优先”的原则，把文档作为设计过程的一部分，而不是事后补充。正如 Rob Pike 所说：”文档是给用户看的，注释是给维护者看的。”

16. Not using linters (未使用 linters)

TL;DR

To improve code quality and consistency, use linters and formatters.

A linter is an automatic tool to analyze code and catch errors. The scope of this section isn’t to give an exhaustive list of the existing linters; otherwise, it will become deprecated pretty quickly. But we should understand and remember why linters are essential for most Go projects.

However, if you’re not a regular user of linters, here is a list that you may want to use daily:

https://golang.org/cmd/vet—A standard Go analyzer
https://github.com/kisielk/errcheck—An error checker
https://github.com/fzipp/gocyclo—A cyclomatic complexity analyzer
https://github.com/jgautheron/goconst—A repeated string constants analyzer

Besides linters, we should also use code formatters to fix code style. Here is a list of some code formatters for you to try:

https://golang.org/cmd/gofmt—A standard Go code formatter
https://godoc.org/golang.org/x/tools/cmd/goimports—A standard Go imports formatter

Meanwhile, we should also look at golangci-lint (https://github.com/golangci/golangci-lint). It’s a linting tool that provides a facade on top of many useful linters and formatters. Also, it allows running the linters in parallel to improve analysis speed, which is quite handy.

Linters and formatters are a powerful way to improve the quality and consistency of our codebase. Let’s take the time to understand which one we should use and make sure we automate their execution (such as a CI or Git precommit hook).

核心观点：使用 linter 和格式化工具是提高 Go 代码质量的关键实践。它们能自动发现潜在问题、保持代码一致性，并强制执行最佳实践。

Data Types

17. Creating confusion with octal literals

Refer

https://github.com/teivah/100-go-mistakes
https://100go.co/

Pithy Wisdom: Go Proverbs for Philosophy and Pedagogy

2025-12-24T12:30:00+08:00

Go 箴言的起源与目的
关于并发与同步的核心观点
接口与抽象的设计哲学
软件工程与代码质量
错误处理与底层机制
文档与命名
Refer

Rob Pike 在 2015 年 Gopherfest 上的演讲，探讨了如何通过 “编程谚语”来传达 Go 语言的核心哲学。他借鉴了围棋中富有诗意且内涵丰富的教导方式，提出了诸如“通过通信共享内存”和“清晰优于聪明”等简洁名言。这些谚语不仅是初学者的教学工具，更封装了关于并发处理、接口设计和依赖管理的深刻工程实践。作者强调，Go 语言的真正力量不仅在于语法，更在于其社区形成的独特编程文化与思维方式。通过这些易于记忆的准则，开发者能够更直观地理解如何编写更具可维护性与鲁棒性的代码。

学习 Go 语言就像学习烹饪。语法是识别食材和刀具，而这些箴言就像是顶级厨师总结出的“火候秘籍”。它们并不规定你必须切多大的块，但会告诉你“过度的调料会掩盖食材的原味”，指引你做出清爽且高质量的佳肴。

02:42 Don’t communicate by sharing memory, share memory by communicating.
03:42 Concurrency is not parallelism.
04:20 Channels orchestrate; mutexes serialize.
05:18 The bigger the interface, the weaker the abstraction.
06:25 Make the zero value useful.
07:36 interface{} says nothing.
08:43 Gofmt’s style is no one’s favorite, yet gofmt is everyone’s favorite.
09:28 A little copying is better than a little dependency.
11:10 Syscall must always be guarded with build tags.
11:52 Cgo must always be guarded with build tags.
12:37 Cgo is not Go.
13:50 With the unsafe package there are no guarantees.
14:34 Clear is better than clever.
15:23 Reflection is never clear.
16:13 Errors are values.
17:27 Don’t just check errors, handle them gracefully.
18:10 Design the architecture, name the components, document the details.
19:08 Documentation is for users.

Go 箴言的起源与目的

灵感来源：概念源自围棋（Go game）中的“围棋谚语”，用于向学习者传授复杂的模式和策略。
教学价值：它们被用作一种教学工具（Pedagogy），帮助开发者超越简单的语法学习，理解 Go 语言背后的深层哲学和架构决策。
核心特性：有效的箴言应当是简短、通用且具有启发性的，即使它们在某些工程场景下可能互相对立。

关于并发与同步的核心观点

不要通过共享内存来通信，而要通过通信来共享内存：这是最著名的 Go 箴言，强调通过通道（Channel）传递指针或对象所有权，以实现安全的并发。
并发（Concurrency）不等于并行（Parallelism）：并发是关于程序结构的组织（使其可扩展、易理解），而并行是关于多任务的同时执行。
通道负责编排，互斥锁负责序列化：互斥锁（Mutexes）用于细粒度的内存保护，而通道（Channels）用于协调程序的大规模结构。

接口与抽象的设计哲学

接口越大，抽象越弱：强大的抽象（如 io.Reader）通常只有极少的方法。接口越小，复用性和组合性就越强。
空接口（interface{}）不传达任何信息：过度使用空接口会丧失静态检查的优势。开发者应尽量定义具体的接口方法来明确意图。

软件工程与代码质量

让零值（Zero Value）变得有用：优秀的 API 设计应确保类型的零值无需显式初始化即可直接使用（如 sync.Mutex 或 bytes.Buffer）
宁可少量的拷贝，也不要增加依赖：为了保持依赖树的精简和编译速度，有时拷贝几行代码比引入一个庞大的库更明智。
清晰胜过聪明：Go 追求代码的可维护性和稳定性，不鼓励追求极度紧凑或深奥的“聪明”写法。
gofmt 的风格没人喜欢，但它是每个人的最爱：标准化的格式化工具虽然不能满足所有人的审美，但消除了关于代码样式的无谓争论。

错误处理与底层机制

错误是值（Errors are values）：不要仅仅把错误当成异常处理，它们是可以被编程、存储和传递的对象。
不要只检查错误，要优雅地处理它们：开发者应考虑如何对错误进行包装或根据错误采取具体行动，而不仅仅是向上层返回。
警惕 Cgo、Unsafe 和反射
- CGO 不是 Go：使用 CGO 会破坏内存安全、垃圾回收和跨平台稳定性。
- 反射永不清晰：反射非常强大但难以使用且缺乏编译时检查，建议初学者远离。
- unsafe 包没有任何保证：使用它意味着代码可能在未来的版本中失效。

文档与命名

设计架构，命名组件，记录细节：良好的命名应承担表达设计意图的主要责任。
文档是给用户看的：编写文档（GoDoc）时应站在使用者的角度，而非实现者的角度。

Refer

Gopherfest 2015 - Go Proverbs with Rob Pike
https://www.youtube.com/@golang
https://notebooklm.google.com/notebook/fe1d8b50-fdaa-4be5-aa92-524039b32f81 (NotebookLM 解读)

NotebookLM in Action

2025-12-24T08:30:00+08:00

核心功能
使用场景
使用方法
实用技巧与注意事项
使用示例
限额问题
Refer

参考 NotebookLM 的维基百科，NotebookLM 是 Google 实验室推出的一款在线笔记本，NotebookLM 内置 Gemini，它可以根据用户上传的内容生成摘要、注解和用户想要的答案。除了文本文件，用户还可以上传 PDF 文档格式、Google 文档、网站和 Google 演示稿。此外用户上传文件后，NotebookLM 可以根据文件内容生成 Podcast 以及音频文件，并在 Podcast 中概述文件内容。NotebookLM 于 2023 年推出，当时名为 Project Tailwind。

Notebook + Language Model = NotebookLM

其核心理念是 “先给你的 AI 提供资料，再让它基于资料帮你工作” 。它不像 ChatGPT 那样拥有通用知识库，而是专注于分析和理解你上传的文档，并在此基础上与你深度互动。

NotebookLM 是一个强大的“第二大脑”或“研究副驾驶”。它最适合那些需要深度处理、消化和转化现有文档信息的任务，将静态资料转化为动态的、可交互的知识库，显著提升研究和内容创作的效率。

核心功能

资料源驱动

可以上传多种格式的文档（PDF、TXT、Word、Google Docs、甚至复制粘贴的文本）。
AI 的知识范围将严格限定在你提供的资料内，回答会带有引用来源（指向原文的特定段落），大大提高了可信度和可追溯性。

三大核心功能

总结与问答：快速生成文档摘要、提取关键要点，并可以针对文档内容进行深度提问。
创意生成：基于你提供的资料，生成新的内容，如博客文章大纲、营销邮件、剧本创意、学习计划等。
思维拓展：帮你连接不同文档中的观点，或基于资料进行批判性思考和分析。

“笔记本”工作区：

每个项目都是一个“笔记本”，你可以持续向其中添加多个相关文档（目前最多 50 个），构建一个专属的知识库。

使用场景

学术研究：学生可以上传论文、教科书章节，让 NotebookLM 总结要点、解释复杂概念、准备考试问答。
内容创作：创作者上传采访记录、背景资料，让 AI 帮忙起草文章、生成创意角度或社交媒体帖子。
商业分析：上传市场报告、会议纪要、竞争对手信息，快速生成综合分析、SWOT 分析或执行摘要。
个人知识管理：阅读大量资料时，上传所有内容，让AI帮你梳理脉络、提炼核心思想，形成个人知识库。
高效阅读：快速消化长文档、法律合同或技术手册，通过问答快速定位关键信息。

使用方法

访问与创建
- 访问 NotebookLM 官网，使用谷歌账号登录。
- 点击 “New Notebook” 创建一个新笔记本，并为其命名。
上传资料
- 在笔记本中，点击 “Add source”（添加来源）。
- 选择上传文件（支持 PDF、DOCX、TXT 等）、粘贴文本，或直接导入 Google Docs。
与AI互动
- 资料上传后，右侧的 AI 聊天界面会自动激活。
- 自动生成建议问题：NotebookLM 会基于文档内容，自动在界面左侧生成几个推荐问题，点击即可快速提问。
- 自由提问：你也可以在底部的输入框中提出任何关于文档内容的问题。
- 使用功能按钮：界面提供了一些快捷功能按钮，如“Summarize this”（总结）、“Create study guide”（创建学习指南）等，一键生成所需内容。
进行创意写作
- 告诉 AI 你的写作目标（例如：“基于这三份资料，写一封向客户介绍新功能的邮件”）。
- AI 会生成草稿，你可以要求它调整语气、长度或重点。
管理多个资料源
- 在一个笔记本中添加所有相关文档，AI 会交叉引用所有内容来回答问题，实现知识的融合。

实用技巧与注意事项

从具体问题开始：问题越具体，得到的答案越精确。
要求引用来源：对于关键信息，可以追问“这个观点在原文的哪一部分？”，AI 会高亮显示原文出处。
多轮对话：像与专家对话一样，可以基于上一个回答深入追问，进行层层剖析。
目前限制：处于实验阶段，免费使用，但可能有时长或功能限制；处理非英语资料的能力可能较弱；对上传的文档数量有上限。

使用示例

以 YouTube 上的 How to achieve concurrency 的视频为例：

导入后会生成如下信息：https://notebooklm.google.com/notebook/db903978-6d35-4aac-a877-ce974b9820b4

这段视频教程介绍了如何利用 Go 语言的原生特性来优化程序执行效率。作者指出，传统的同步处理方式在面对文件读写等耗时操作时速度较慢，而通过 Goroutines（协程）可以同时独立运行多个任务。为了管理这些并发任务，开发者可以使用 Channels（通道）像管道一样在不同进程间传递数据。这种机制不仅能实现异步编程，还能确保主程序在获取到必要结果前处于自动阻塞等待状态。通过结合这两大核心功能，程序员能够以更简洁的代码处理复杂的并发任务。

主要有以下几个功能：

生成中文的音频

可以对此内容生成中文的音频概览，对于英文不好的用户比较友好，但是免费场景，每日有使用次数限制。

生成思维导图

支持生成思维导图，并可以根据思维导图选择的关键信息进行 Deep Research 深度解释。

输出报告

输出一份最佳实践报告：

生成闪卡

同时支持导出：

测验

信息图

演示文稿

限额问题

升级到 Google AI Pro，获享更高的 NotebookLM 限额及更多福利。

精选方案：https://one.google.com/u/0/explore-plan/notebooklm?utm_source=notebooklm&utm_medium=web&utm_campaign=audio_overview_limit&ms=pt:1285;s:532;vp:9
更多方案：https://one.google.com/ai?g1_last_touchpoint=62&g1_landing_page=75

Refer

https://notebooklm.google.com/
https://zh.wikipedia.org/zh-cn/NotebookLM

Gerry’s blog

Minimax in Action

MiniMax

在 Claude Code 中使用 MiniMax-M2.1

安装 Claude Code

获取 API Key

Coding Plan API Key

开放平台 API Key（按量计费）

配置 MiniMax API

安装 cc-switch

申请 MiniMax API Key

添加 MiniMax 配置

配置模型名称

启用配置

启动 Claude Code

信任文件夹

执行 /init 命令生成 CLAUDE.md

Claude Code CLI 的 Bash 脚本包装器

在 VS Code 使用 Claude Code 生成网页时钟的测试

在 Cursor 中使用 MiniMax-M2.1

安装 Cursor

在 Cursor 中配置 MiniMax API

在 Cursor 中使用 MiniMax-M2.5

在 OpenClaw 中使用 MiniMax-M2.5

打开配置设置

选择配置选项

登陆授权

确认模型选择

重启 gateway 使配置生效

测试对话

Refer

OpenClaw - Personal AI Assistant

快速开始

使用示例

在 tui 终端对话

通过 QQ 客户端对话

配置 HTTP 服务

实现小游戏

生成图片

生成音乐

生成视频

Skills 最佳实践

Find Skills 发现其他好用的 Skill

ClawSec 安全防护

Self-Improving Agent AI 自我进化

Tavily Web Search 让 AI 拥有实时信息获取能力

Multi Search Engine 适合中文信息搜索

GitHub 代码仓库的自然语言管理

Proactive Agent 从被动相应到主动服务

Debug Methodology 问题调试

Skills 数据备份和恢复 (重要)

背景介绍

Quick Start

Moltbot (原 Clawdbot)

What It Does

Works With Everything

Install the CLI (recommended)

Uninstall

Run the onboarding wizard (and install the service)

Auth: where it lives (important)

Start the Gateway

Quick verify (2 min)

Channles

Imessage

Quick setup (beginner)

使用 lighthouse 部署 OpenClaw 全能助手

购买 OpenClaw 云服务

配置 OpenClaw

QQ开放平台申请机器人

Web Search 能力

配置 Brave API (收费)

配置 finnhub (免费)

配置 tavily (免费)

更多用法

常用命令

打开终端

查看帮助

初始化配置

配置向导

查看配置

执行 `/init` 命令生成 `CLAUDE.md`