看完这篇，你能得到一套可以直接抄走的生产配置： 域名写进配置就自动申请、自动续期 HTTPS 证书（含泛域名），永远不用再碰 cron； 访问日志从「看不懂的 JSON」改造成熟悉的 Nginx/Apache 纯文本格式，还能自动轮转； 全部服务用 Docker Compose 编排，改配置不断线热加载。

整体思路分三层，各管一摊：

• 软件交给 Homebrew，CLI 工具和 GUI 应用都靠它一条命令装齐；
• 配置交给 chezmoi，dotfiles 已托管在 GitHub，一行命令完成接管；
• 语言运行时交给 vfox，用到哪个版本再装，不提前锁死。

主流程走完即得到一套可用环境；标注「可选」的换源、Docker、第三方应用等不影响主线，按需取用即可。下面按实际操作顺序展开。

WSL Docker

window 主机使用 usbipd-win

usbipd list
usbipd bind --busid=<BUSID>

usbipd attach --wsl --busid=<BUSID>

Docker 容器直接挂载 /dev 目录就能直接用了，例如：docker run --rm -it --privileged -v /dev:/dev debian:bookworm bash

Devcontainer json 配置：

{
  // ...
  "mounts": [
    // Allow attaching USB devices to running container
    "source=/dev,target=/dev,type=bind"
  ]
  // ...
}

Mac Docker

macOS 主机使用 usbip，需要 rust 环境

git clone https://github.com/jiegec/usbip.git
cd usbip
cargo build --release

cargo run --example host

容器安装 usbip client

# Debian
docker run --rm -it --privileged --pid=host debian:bookworm bash
apt update && apt install -y usbip

# Ubuntu / Debian
docker run --rm -it --privileged --pid=host ubuntu:22.04 bash
apt update && apt install -y linux-tools-virtual hwdata
update-alternatives --install /usr/local/bin/usbip usbip $(command -v ls /usr/lib/linux-tools/*/usbip | tail -n1) 20

# Alpine
docker run --rm -it --privileged --pid=host alpine
apk update && apk add -y linux-tools-usbip hwdata

容器连接宿主机 USB 设备

# List available devices
usbip list -r $remote_ip

# Attach to a device
usbip attach -r $remote_ip -b $bus_id

常用系统快捷键速查表

终端快捷键速查表

实用小技巧

1. 快速预览：选中文件按 空格键 预览内容，无需打开应用
2. 强制退出应用：Option + Cmd + Esc 打开强制退出窗口
3. 清空废纸篓：Shift + Cmd + Delete 永久删除文件（跳过废纸篓）
4. 快捷键提示：按住 Cmd 键可查看当前应用的所有快捷键

参考

• https://github.com/macdao/ocds-guide-to-setting-up-mac?tab=readme-ov-file
• https://kangod.top/blog/setting-up-mac-terminal
• https://linux.do/t/topic/507031/23
• https://linux.do/t/topic/509377

✨ 特性

• 🔍 智能检查: 自动检测容器使用的镜像是否有新版本可用
• 🏷️ 标签驱动: 通过 watchducker.update=true 标签自动管理需要更新的容器
• ⏰ 定时执行: 支持使用 cron 表达式进行定时检查
• 🔄 自动更新: 检测到更新后可自动重启容器使用新镜像
• 🚫 灵活控制: 提供只检查不重启的选项
• ✨ 实时反馈: 检查过程中提供实时进度和结果输出
• 🐳 Docker 原生: 完全基于 Docker API，无需额外依赖
• ⚙️ 无需代理: 复用现有 Docker 配置，无需额外配置认证和代理、加速镜像源
• 📢 多平台通知: 支持 Telegram、微信、钉钉、飞书、邮件等 15+ 种通知方式

🚀 快速开始

二进制安装

从 Releases 页面 下载对应平台的二进制文件：

Docker 镜像

docker pull naomi233/watchducker:latest

源码编译

git clone https://github.com/naomi233/watchducker.git
cd watchducker
go build -o watchducker .

📖 使用方法

Docker

# 检查指定容器一次
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --once nginx redis mysql
# 检查所有带有更新标签的容器一次
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --label --once
# 检查所有容器一次，更新后清理悬空镜像
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --all --clean --once
# 只更新镜像，不重启容器
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --no-restart --once nginx redis
# 使用标签模式，同时防止自动重启
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --label --no-restart --once
# 每天凌晨2点检查所有标签容器
docker run --name watchducker -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --cron "0 2 * * *" --label
# 每30分钟检查指定容器
docker run --name watchducker -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --cron "*/30 * * * *" nginx redis
# 每天执行，只检查不重启
docker run --name watchducker -v /var/run/docker.sock:/var/run/docker.sock naomi233/watchducker:latest watchducker --cron "@daily" --no-restart nginx

# 使用通知功能（方式一：挂载配置文件）
docker run --name watchducker -v /var/run/docker.sock:/var/run/docker.sock -v $(pwd)/push.yaml:/app/push.yaml naomi233/watchducker:latest watchducker --cron "0 2 * * *" --label

# 使用通知功能（方式二：环境变量，无需挂载配置文件）
docker run --name watchducker \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHDUCKER_SETTING_PUSH_SERVER=telegram \
  -e WATCHDUCKER_TELEGRAM_API_URL=api.telegram.org \
  -e WATCHDUCKER_TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN \
  -e WATCHDUCKER_TELEGRAM_CHAT_ID=YOUR_CHAT_ID \
  naomi233/watchducker:latest watchducker --cron "0 2 * * *" --label

可执行文件

# 检查指定容器一次
watchducker --once nginx redis mysql
# 检查所有带有更新标签的容器一次
watchducker --label --once
# 检查所有容器一次，更新后清理悬空镜像
watchducker --all --clean --once
# 只更新镜像，不重启容器
watchducker --no-restart --once nginx redis
# 使用标签模式，同时防止自动重启
watchducker --label --no-restart --once
# 每天凌晨2点检查所有标签容器
watchducker --cron "0 2 * * *" --label
# 每30分钟检查指定容器
watchducker --cron "*/30 * * * *" nginx redis
# 每天执行，只检查不重启
watchducker --cron "@daily" --no-restart nginx
# 使用 --label-reversed 参数检查所有容器，排除带有 watchducker.update=true 标签的容器
watchducker --label-reversed --once

# 使用通知功能（需要配置 push.yaml）
watchducker --cron "0 2 * * *" --label

Docker Compose 配置示例

services:
  watchducker:
    image: naomi233/watchducker
    container_name: watchducker
    network_mode: bridge
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./push.yaml:/app/push.yaml # 挂载通知配置文件
    environment:
      - TZ=Asia/Shanghai
      - WATCHDUCKER_LOG_LEVEL=DEBUG
      - WATCHDUCKER_CRON=0 2 * * *
      - WATCHDUCKER_LABEL=true

⚙️ 配置选项

命令行参数

• --all: 检查所有容器（默认仅包含运行中的容器）
• --label: 检查带有 watchducker.update=true 标签的容器
• --label-reversed: 检查没有 watchducker.update=true 标签的容器
• --cron: 定时执行，使用标准 cron 表达式 格式，默认值 "0 2 * * *"
• --once: 只执行一次检查和更新，然后退出
• --clean: 更新容器后自动清理悬空镜像
• --no-restart: 只更新镜像，不重启容器
• --include-stopped: 在检查时包含已停止的容器
• --disabled-containers: 排除指定的容器，不进行检查和更新（支持逗号分隔多个容器）
• 容器名称列表

通知功能配置

WatchDucker 支持同时使用多种通知渠道，可通过 push.yaml 配置文件或环境变量进行配置。

方式一：配置文件（推荐）

setting:
  push_server: "telegram" # 推送服务列表（支持多渠道 用,分开）
  log_level: "DEBUG" # 日志级别：DEBUG/INFO/WARN/ERROR

telegram:
  api_url: "api.telegram.org" # Telegram API地址（支持反代）
  bot_token: "YOUR_BOT_TOKEN" # 机器人Token
  chat_id: "YOUR_CHAT_ID" # 聊天ID


# 其他通知方式配置...

方式二：环境变量（无需挂载配置文件）

环境变量会覆盖配置文件中的对应值，格式为 WATCHDUCKER_ + 配置路径（用下划线连接）：

# 基础配置
export WATCHDUCKER_SETTING_PUSH_SERVER="telegram,dingrobot"
export WATCHDUCKER_SETTING_LOG_LEVEL="INFO"

# Telegram 配置
export WATCHDUCKER_TELEGRAM_API_URL="api.telegram.org"
export WATCHDUCKER_TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
export WATCHDUCKER_TELEGRAM_CHAT_ID="YOUR_CHAT_ID"

# 钉钉配置
export WATCHDUCKER_DINGROBOT_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export WATCHDUCKER_DINGROBOT_SECRET="SECxxx"

Docker Compose 环境变量示例：

services:
  watchducker:
    image: naomi233/watchducker
    container_name: watchducker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Shanghai
      - WATCHDUCKER_CRON=0 2 * * *
      - WATCHDUCKER_LABEL=true
      # 通知配置（无需挂载 push.yaml）
      - WATCHDUCKER_SETTING_PUSH_SERVER=telegram
      - WATCHDUCKER_TELEGRAM_API_URL=api.telegram.org
      - WATCHDUCKER_TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
      - WATCHDUCKER_TELEGRAM_CHAT_ID=YOUR_CHAT_ID

支持的通知服务：

• Telegram: 机器人推送
• Server 酱 （FTQQ）: 微信推送
• PushPlus: 微信推送
• CQHTTP: QQ 推送
• SMTP: 邮件推送
• 企业微信: 应用消息和群机器人
• PushDeer: 自建推送服务
• 钉钉: 群机器人
• 飞书: 群机器人
• Bark: iOS 推送
• Gotify: 自建推送服务
• IFTTT: Webhook 触发
• Webhook: 自定义 Webhook
• Qmsg: QQ 消息推送
• Discord: Webhook 推送

环境变量

# 设置容器时区（默认 UTC，可按需覆盖）
export TZ=Asia/Shanghai

# 设置日志级别 (DEBUG/INFO/WARN/ERROR)
export WATCHDUCKER_LOG_LEVEL=DEBUG

# 等同于 --all 选项
export WATCHDUCKER_ALL=true

# 等同于 --label 选项
export WATCHDUCKER_LABEL=true

# 等同于 --label-reversed 选项
export WATCHDUCKER_LABEL_REVERSED=true

# 等同于 --cron 选项
export WATCHDUCKER_CRON="0 2 * * *"

# 等同于 --clean 选项
export WATCHDUCKER_CLEAN=true

# 等同于 --no-restart 选项
export WATCHDUCKER_NO_RESTART=true

# 等同于 --include-stopped 选项
export WATCHDUCKER_INCLUDE_STOPPED=true

# 等同于 --disabled-containers 选项
export WATCHDUCKER_DISABLED_CONTAINERS="container1,container2"

时区配置

容器镜像默认按照 UTC 运行。只需通过标准 TZ 环境变量（如 -e TZ=Asia/Shanghai，或在 Compose/环境配置中设置 TZ ）即可让容器启动时自动切换到目标时区，无需额外挂载 /etc/localtime。

使用标签驱动更新

为需要自动更新的容器添加标签：

docker run --name nginx --label watchducker.update=true nginx:latest

🏗️ 项目架构

目录结构

watchducker/
├── cmd/                    # 命令行入口
│   └── cmd.go               # 主命令逻辑
├── internal/                 # 内部模块
│   ├── core/                # 核心业务逻辑
│   │   ├── checker.go         # 镜像检查器
│   │   └── operator.go      # 容器操作器
│   ├── docker/               # Docker API 封装
│   │   ├── client.go         # 客户端管理
│   │   ├── container.go     # 容器服务
│   │   └── image.go          # 镜像服务
│   └── types/                 # 类型定义
│       └── types.go
├── pkg/                      # 可复用的公共包
│   ├── config/                # 配置管理
│   │   └── config.go
│   ├── logger/               # 日志系统
│   │   └── logger.go
│   ├── notify/               # 通知系统
│   │   └── notify.go         # 多平台通知服务
│   └── utils/                 # 工具函数
│       └── display.go         # 显示输出
├── main.go                    # 程序入口
├── push.yaml.example         # 通知配置示例文件

核心组件

• Checker: 镜像检查器，负责检查容器使用的镜像是否有更新
• Operator: 容器操作器，负责容器的重启和更新操作
• ContainerService: 容器服务，封装 Docker 容器的操作
• ImageService: 镜像服务，封装 Docker 镜像的检查逻辑
• NotifyService: 通知服务，支持 15+ 种通知方式推送更新结果

🔧 开发

依赖要求

• Go 1.25 或更高版本
• Docker 守护进程（用于容器操作）
• 网络连接（用于镜像仓库访问）

项目构建

# 开发构建
go build -o watchducker .

# 多平台发布（使用 GoReleaser）
goreleaser build --snapshot

# 创建 Docker 镜像
goreleaser release --snapshot

📊 工作流程

1. 容器发现: 根据容器名称或标签查找相关容器
2. 镜像检查: 并发检查所有镜像是否有更新版本
3. 自动更新: 停止旧容器 → 删除旧容器 → 创建新容器 → 启动新容器

🔐 安全性

• 只对指定标签的容器进行操作
• 提供清晰的日志记录所有操作
• 支持只检查模式，避免意外重启

🐛 故障排除

常见问题

1. 权限错误: 确保程序有足够的权限访问 Docker 守护进程
2. 网络连接: 检查是否有网络连接访问镜像仓库
3. 容器状态: 确保目标容器处于运行状态

调试模式

# 启用调试日志
export WATCHDUCKER_LOG_LEVEL=DEBUG
watchducker --label

先贤赫拉克利特曾断言“冲突是万物之父”，红黑树以其结构性智慧印证此道。那五项规则——根必玄墨、叶皆虚玄、赤不生赤、黑径等深——并非僵硬的桎梏，而是生命在矛盾中蓬勃的韵律。每一次插入，都带着革命性的赤红，如马尔库塞批判理论中的“大拒绝”，挑战着既存的墨色秩序；而随之而来的旋转与变色，并非惩罚，乃是系统以辩证的智慧将异质吸纳为新生力量。这恰如黑格尔所指，规则在自身的否定中达成更高级的肯定，每一次看似破坏平衡的操作，实则是在深化平衡的本质。

然而，红黑树的深邃在于其“近似平衡”的东方智慧。它不追求 AVL 树那般绝对的几何对称，而是以墨色路径的等长作为不可撼动的基石，允许在局部保留适度的赤色跃动。这暗合了老子“知其白，守其黑”的玄理——那墨色主干是寂然不动的道体，而赤色节点则是生生不息的德用。我们栖居于这样的结构，学会在规制的“黑”与创新的“红”之间寻求中道。亚里士多德的德性论在此找到了数字化身：树的健康既非源于颜色的纯粹，亦非混沌的杂多，而在于二者间那种富有张力的和谐。

诚然，对规则的恪守是栖居的前提，但真正的智慧在于理解规则背后那流动的理性。奥斯卡·王尔德曾言：“真正的完美不在于无可增减，而在于无可删改。”红黑树的完美，正体现在其面对连续插入时，仅需区区数次旋转便能恢复根本秩序。这种“不完美的完美”，这种在动态中维持的优雅，正是应对存在之流变的最高智慧。它告诉我们，栖居并非静态的占有，而是在遵守核心规制的前提下，与变化共舞的艺术。

生活在红黑树上，便是接受一种在约束中勃发的生命形式。墨色路径是我们走向世界的坚实轨道，给予存在以基本的确定性与深度；赤色节点则是轨道上绽放的思想之花，为结构注入活力与可能。我们以赤色点燃变革的勇气，以墨色沉淀生命的厚度。在这赭墨交织的经纬中，我们既拥抱了必要的规制，又未曾泯灭创造的火焰，最终抵达一种如红黑树般——在动态中保持深邃，在约束中实现自由的、圆融的数字化生存。

配置特色

• 降低 DNS 泄漏和污染风险：国内域名优先使用国内 DNS，未命中规则的境外域名使用境外 DoH，并让相关请求遵循代理规则。
• 支持多个订阅：可在 proxy-providers 中添加多个订阅源，节点与规则相互分离，更方便维护和更新。
• 自动更新资源：定时更新 GeoIP、GeoSite、RuleSet 规则集和订阅节点，减少手动维护成本。
• 自动分类节点：根据名称筛选香港、台湾、日本、韩国、新加坡、美国、家宽、流媒体等节点。
• 细分常用服务：为 AI、流媒体、游戏平台、微软、苹果、Google 等服务提供独立策略组，可按需选择线路。
• 多种选路策略：同时提供手动选择、最低延迟、故障转移和负载均衡，兼顾速度与稳定性。
• 内置基础广告拦截：使用 GeoSite 广告分类规则拦截常见广告域名。
• 优化 Google Play 商店体验：优化特供版 Google Play 商店访问、应用下载和更新的稳定性，不再卡 99%。

使用前说明

• 请使用支持此配置语法的 Mihomo 内核或客户端。
• 订阅地址需要是 Clash/Mihomo 兼容格式；其他格式可先通过 ACL4SSR 在线订阅转换 处理。
• 配置默认关闭局域网访问和 TUN 模式。如需接管系统全部流量，请根据自己的客户端与系统环境启用 TUN。
• external-controller 默认监听所有网卡。若设备可能被他人访问，建议设置 secret，或将监听地址改为 127.0.0.1:9090。

配置内容

复制下面的 YAML，将 proxy-providers 中的 <订阅名称> 和 <订阅地址> 替换为自己的信息，然后导入客户端并重新加载配置。需要添加多个订阅时，按相同格式继续增加即可，例如：

proxy-providers:
  subscription-a:
    url: "https://example.com/subscribe-a"
    <<: *ProxySet
  subscription-b:
    url: "https://example.com/subscribe-b"
    <<: *ProxySet

启用后，可以使用 BrowserLeaks、DNSLeakTest 或 IPLeak 检查 DNS 解析结果。测试结果仍可能受客户端实现、系统设置和网络环境影响。

mode: rule
mixed-port: 7890
log-level: info
ipv6: false
bind-address: "*"
allow-lan: false
lan-allowed-ips:
  - 127.0.0.1/8
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16
  - fe80::/10

secret: ""
external-controller: "0.0.0.0:9090"
external-ui: ui
external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip"

geodata-mode: true
geo-auto-update: true
geo-update-interval: 48
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country.mmdb"
  asn: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/GeoLite2-ASN.mmdb"

### TUN配置
tun:
  enable: false
  stack: mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true
  strict-route: true # 严格路由模式 windows平台防止dns泄露

### DNS配置
dns:
  enable: true
  ipv6: false
  prefer-h3: false
  use-hosts: false
  use-system-hosts: true
  enhanced-mode: "fake-ip"
  fake-ip-range: "198.18.0.1/16"
  fake-ip-filter:
    - rule-set:fakeip-filter
    - geosite:private
    - geosite:tracker
  default-nameserver: # 基础DNS服务器，必须先有它才能使用域名类型的DNS配置，因此必须为IP，此处使用阿里云DNS
    - "system"
    - tls://223.5.5.5
    - tls://223.6.6.6
  nameserver: # 在访问的国外网站没有匹配到任何域名规则，最终走了MATCH兜底规则时使用的DNS，为了确保不发生DNS泄漏和DNS污染，必须使用国外DNS
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  proxy-server-nameserver: # 解析代理节点时使用的DNS，为了使下面的respect-rules生效必须设置，最好设置为国内DNS，否则在代理的第一步就可能因为连接不上国外DNS而解析不出代理节点的IP，最终倒在起点
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  direct-nameserver: # 规则匹配到直连时使用的DNS，既然是可以直连的，当然要用国内DNS
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  respect-rules: true # 让连接DNS服务器时能够遵循规则，也就是通过代理节点连接到上面设置的国外DNS，因为直连可能连接不上
  # direct-nameserver-follow-policy: true # 让下面设置的nameserver-policy生效
  # nameserver-policy:
  #   +.<内网域名>: "system"

### 规则配置
RuleSet_classical: &RuleSet_classical
  type: http
  behavior: classical
  interval: 86400
  proxy: DIRECT

RuleSet_domain: &RuleSet_domain
  type: http
  behavior: domain
  interval: 86400
  proxy: DIRECT

RuleSet_ipcidr: &RuleSet_ipcidr
  type: http
  behavior: ipcidr
  interval: 86400
  proxy: DIRECT

rule-providers:
  fakeip-filter:
    <<: *RuleSet_domain
    format: mrs
    url: "https://github.com/DustinWin/ruleset_geodata/releases/download/mihomo-ruleset/fakeip-filter.mrs"

### 节点池配置
ProxySet: &ProxySet
  type: http
  proxy: DIRECT
  interval: 43200
  health-check:
    enable: true
    url: "https://www.gstatic.com/generate_204"
    interval: 600
  # 节点前缀（节点名称中会自动加上这个前缀，方便区分不同来源的节点）
  override:
    additional-prefix: ""
    skip-cert-verify: true

### 订阅池配置
proxy-providers:
  <订阅名称>:
    url: "<订阅地址>"
    <<: *ProxySet
    # override:
    #   additional-prefix: "前缀"

# 节点筛选（必须用引号包裹正则表达式）
FilterHK: &FilterHK "^(?=.*((?i)🇭🇰|香港|港|HK|Hong))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterTW: &FilterTW "^(?=.*((?i)🇹🇼|台湾|台|新北|彰化|TW|Taiwan))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterJP: &FilterJP "^(?=.*((?i)🇯🇵|日本|川日|东京|大阪|泉日|埼玉|沪日|深日|JP|Japan))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterKR: &FilterKR "^(?=.*((?i)🇰🇷|韩国|韩|韓|首尔|KR|Korea|KOR))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterSG: &FilterSG "^(?=.*((?i)🇸🇬|新加坡|坡|狮城|SG|Singapore))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterUS: &FilterUS "^(?=.*((?i)🇺🇸|美国|美|波特兰|达拉斯|俄勒冈|凤凰城|费利蒙|硅谷|拉斯维加斯|洛杉矶|圣何塞|圣克拉拉|西雅图|芝加哥|US|United States|UnitedStates|America))(?!.*((?i)回国|校园|游戏|🎮|教育|久虚|网站|地址|剩余|过期|时间|有效|网址|禁止|邮箱|发布|客服|订阅|节点|家宽)).*$"
FilterNetflix: &FilterNetflix "^(?=.*((?i)NF|奈飞|解锁|Netflix|NETFLIX|Media))(?!.*((?i)家宽)).*$"
FilterHomeWidth: &FilterHomeWidth "^(?=.*((?i)家宽)).*$"
FilterSpecialRate: &FilterSpecialRate '^(?=.*((0\.01|0\.02|0\.03|0\.04|0\.05|0\.06|0\.07|0\.08|0\.09|0\.1|0\.2|0\.3|0\.4|0\.5|0\.6|0\.7|0\.8|0\.9|1\.5|2|2\.5|3|3\.5|4|4\.5|5|5\.5|6|6\.5|7|7\.5|8|8\.5|9)(X|x|×)|(X|x|×)(0\.01|0\.02|0\.03|0\.04|0\.05|0\.06|0\.07|0\.08|0\.09|0\.1|0\.2|0\.3|0\.4|0\.5|0\.6|0\.7|0\.8|0\.9|1\.5|2|2\.5|3|3\.5|4|4\.5|5|5\.5|6|6\.5|7|7\.5|8|8\.5|9)))(?!.*((?i)家宽)).*$'
FilterAll: &FilterAll '^(?=.*(.))(?!.*((?i)群|邀请|返利|循环|官网|客服|网站|网址|获取|订阅|流量|到期|机场|下次|版本|官址|备用|过期|已用|联系|邮箱|工单|贩卖|通知|倒卖|防止|国内|地址|频道|无法|说明|使用|提示|特别|访问|支持|教程|关注|更新|防范|作者|加入|家宽|(\b(USE|USED|TOTAL|EXPIRE|EMAIL|Panel|Channel|Author)\b|(\d{4}-\d{2}-\d{2}|\d+G)))).*$'

### 策略组基础配置
Select: &Select
  type: select
  url: "https://www.gstatic.com/generate_204"
  disable-udp: false
  hidden: false
  include-all: true

UrlTest: &UrlTest
  type: url-test
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  lazy: true
  tolerance: 100
  timeout: 5000
  disable-udp: false
  max-failed-times: 3
  hidden: true
  include-all: true

FallBack: &FallBack
  type: fallback
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  lazy: false
  timeout: 5000
  disable-udp: false
  max-failed-times: 3
  hidden: true
  include-all: true

LoadBalance: &LoadBalance
  type: load-balance
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  lazy: true
  disable-udp: false
  strategy: consistent-hashing
  timeout: 5000
  max-failed-times: 3
  hidden: true
  include-all: true

### 代理组配置
proxy-groups:
  - name: 🚀 节点选择
    type: select
    proxies:
      - ♻️ 稳定自动
      - 🔰 延迟最低
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇯🇵 日本节点
      - 🇰🇷 韩国节点
      - 🇸🇬 狮城节点
      - 🇺🇲 美国节点
      - 🚀 手动切换
      - 🛖 家宽节点
      - DIRECT

  - name: ♻️ 稳定自动
    <<: *FallBack
    filter: *FilterAll
    hidden: false

  - name: 🔰 延迟最低
    <<: *UrlTest
    filter: *FilterAll

  - name: 🚀 手动切换
    <<: *Select
    filter: *FilterAll

  - name: 🤖 AI
    type: select
    proxies:
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🛖 家宽节点
      - 🚀 手动切换

  - name: 🎮 游戏平台
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🔰 延迟最低
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: Ⓜ️ 微软Bing
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: Ⓜ️ 微软云盘
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🔰 延迟最低
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: Ⓜ️ 微软服务
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: 🍎 苹果服务
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: 🇬 谷歌服务
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择
      - ♻️ 稳定自动
      - 🇭🇰 香港节点
      - 🇨🇳 台湾节点
      - 🇸🇬 狮城节点
      - 🇯🇵 日本节点
      - 🇺🇲 美国节点
      - 🇰🇷 韩国节点
      - 🚀 手动切换

  - name: 🎯 全球直连
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择

  - name: 🐟 漏网之鱼
    type: select
    proxies:
      - DIRECT
      - 🚀 节点选择

  - name: 🛑 广告拦截
    type: select
    proxies:
      - REJECT
      - DIRECT

  - name: 🇭🇰 香港节点
    <<: *UrlTest
    filter: *FilterHK

  - name: 🇨🇳 台湾节点
    <<: *UrlTest
    filter: *FilterTW

  - name: 🇯🇵 日本节点
    <<: *UrlTest
    filter: *FilterJP

  - name: 🇰🇷 韩国节点
    <<: *UrlTest
    filter: *FilterKR

  - name: 🇸🇬 狮城节点
    <<: *UrlTest
    filter: *FilterSG

  - name: 🇺🇲 美国节点
    <<: *UrlTest
    filter: *FilterUS
    tolerance: 150

  - name: 🛖 家宽节点
    <<: *UrlTest
    filter: *FilterHomeWidth
    hidden: false

rules:
  - GEOSITE,private,DIRECT
  - GEOIP,private,DIRECT,no-resolve

  # 强制境外 DoH 经过代理
  - IP-CIDR,1.1.1.1/32,🚀 节点选择,no-resolve
  - IP-CIDR,8.8.8.8/32,🚀 节点选择,no-resolve

  - AND,(AND,(DST-PORT,443),(NETWORK,UDP)),(NOT,((GEOSITE,cn))),REJECT
  - AND,(AND,(DST-PORT,443),(NETWORK,UDP)),(NOT,((GEOIP,CN))),REJECT

  - GEOSITE,category-ads-all,🛑 广告拦截

  - GEOSITE,bing,Ⓜ️ 微软Bing
  - GEOSITE,onedrive,Ⓜ️ 微软云盘
  - GEOSITE,microsoft@cn,Ⓜ️ 微软服务
  - GEOSITE,apple@cn,🍎 苹果服务
  - GEOSITE,google@cn,🇬 谷歌服务
  - DOMAIN-SUFFIX,googleapis.cn,🇬 谷歌服务

  - GEOSITE,category-ai-!cn,🤖 AI
  - GEOSITE,category-ai-cn,🎯 全球直连

  - GEOSITE,category-games@cn,🎯 全球直连
  - GEOSITE,category-games,🎮 游戏平台

  - GEOSITE,gfw,🚀 节点选择
  - GEOSITE,cn,🎯 全球直连

  - GEOIP,telegram,🚀 节点选择,no-resolve
  - GEOIP,CN,🎯 全球直连

  - MATCH,🐟 漏网之鱼

警告

在阅读或使用教程前，请您仔细阅读并理解以下免责声明。一旦您开始使用本教程，即表示您已同意接受本声明的所有条款和条件。如您不同意本声明的任何内容，请立即停止使用本教程。​

本教程仅供学习参考，严禁用于任何非法用途。使用者应自行承担所有风险，本人及绿联不对因使用、误用或依赖本教程内容而产生的任何后果或法律责任负责。

在没有公网 IP 的情况下，UGREENlink 可以访问到 NAS ，但只有门户系统提供的功能，无法直接访问 NAS 上的 WebDAV 服务。

这里介绍一种通过 UGREENlink 访问 NAS 上 WebDAV 的方法。

首先，确保你的 NAS 上已经启用了 WebDAV 服务，并记下 WebDAV 的访问地址。

然后，在 UGREENlink 的 Nginx 配置中添加以下内容：

添加文件 /etc/nginx/conf.d/webdav.conf ，内容如下：

location = /dav {
    return 301 $scheme://$http_host/dav/;
}

location ^~ /dav/ {
    proxy_pass http://127.0.0.1:5005/;

    include /etc/nginx/proxy_params;

    proxy_pass_request_headers on;

    proxy_request_buffering off;
    proxy_buffering off;
    client_max_body_size 0;

    proxy_read_timeout 3600s;

    sub_filter '<D:href>' '<D:href>/dav';
    sub_filter_once off;
    sub_filter_types text/xml application/xml;
}

重新加载 Nginx 配置：

sudo systemctl reload nginx

然后就可以通过访问 https://xx.ug.link/dav 来使用 WebDAV 服务，其中 xx.ug.link 是你在访问 https://ug.link/你的UGREENid 时获得的域名。

Go is a new language. Although it borrows ideas from existing languages, it has unusual properties that make effective Go programs different in character from programs written in its relatives. A straightforward translation of a C++ or Java program into Go is unlikely to produce a satisfactory result—Java programs are written in Java, not Go. On the other hand, thinking about the problem from a Go perspective could produce a successful but quite different program. In other words, to write Go well, it's important to understand its properties and idioms. It's also important to know the established conventions for programming in Go, such as naming, formatting, program construction, and so on, so that programs you write will be easy for other Go programmers to understand.

Go 是一门全新的语言。尽管它从现有的语言中借鉴了诸多思想，但它拥有许多非同寻常的特性，使得编写高效程序的方式与其它近亲语言有显著的不同。简单粗暴的将 C++ 或者 Java 的编程思维强加于 Go 之上的话，结果可能不尽如人意（ Java 是 Java， Go 是 Go ）。反之，如果站在 Go 的角度去思考问题，则会柳暗花明，获异曲同工之效。换言之，只有在你了解 Go 的特性，熟悉 Go 的风格之后，你才能用好它。遵循已有的编程惯例和编程规范亦同等重要，诸如命名、格式化、程序结构等等；如此一来，其他的开发者才能更好的理解你编写的程序。

This document gives tips for writing clear, idiomatic Go code. It augments the language specification, the Tour of Go, and How to Write Go Code, all of which you should read first.

本文档就如何编写清晰的、Go 风格化的代码提供了多方面的技巧。请注意，你应该优先阅读 Language Specification、A Tour of Go、How to write Go code 这些文档，本文是对它们的扩充。

Examples

The Go package sources are intended to serve not only as the core library but also as examples of how to use the language. Moreover, many of the packages contain working, self-contained executable examples you can run directly from the golang.org web site, such as this one (if necessary, click on the word "Example" to open it up). If you have a question about how to approach a problem or how something might be implemented, the documentation, code and examples in the library can provide answers, ideas and background.

Go 的源码包不仅仅只作为核心库来提供，它同时也是很好的语言使用范例。而且，很多 package 都包含有效的、自包含的可执行代码示例。你可以直接在 golang.org 站点运行它们，比如说 这个例子，你可以点击 Example 来将代码展开（译注：源码文档中的例子都可以就地运行，也可以 copy 到 The Go Playground 去运行）。如果你有任何关于某个问题如何解决或者某种东西如何实现的疑问，你都可以从文档、源码、以及示例中获得答案或者思路。

02.Formatting 格式化

Formatting issues are the most contentious but the least consequential. People can adapt to different formatting styles but it's better if they don't have to, and less time is devoted to the topic if everyone adheres to the same style. The problem is how to approach this Utopia without a long prescriptive style guide.

格式化 是一个最具争议却又无关大局的问题。纵然人们可以适应不同的格式化风格，但是如果在这件事上让他们少花精力，则是最好不过的事。假如每个人都坚持相同的格式化风格，那么在此问题上就可以节约很多时间。关键是如何达成这一理想，同时又能避免冗长的指导规则。

With Go we take an unusual approach and let the machine take care of most formatting issues. The gofmt program (also available as go fmt, which operates at the package level rather than source file level) reads a Go program and emits the source in a standard style of indentation and vertical alignment, retaining and if necessary reformatting comments. If you want to know how to handle some new layout situation, run gofmt; if the answer doesn't seem right, rearrange your program (or file a bug about gofmt), don't work around it.

在 go 中，我们采用了一种特殊的方式，那就是让机器去处理绝大部分的格式化问题。gofmt 程序（也可以通过 go fmt 来使用，它将在包级别进行操作，而不是文件级别）会读取 go 程序并将源文件格式化为标准风格——统一缩进和垂直对齐、保留注释（如有必要则重新格式化）。如果你对其如何处理新的布局情形有兴趣，那么就运行 gofmt 吧！如果没达到预想的结果，就请重新整理一下代码（或者提交一个关于 gofmt 的 bug），但不要在此耗费过多精力。

As an example, there's no need to spend time lining up the comments on the fields of a structure. Gofmt will do that for you. Given the declaration

如下示例，没必要在结构体字段的注释对齐上面浪费太多时间，Gofmt 会帮你完成。给定一个结构体声明：

type T struct {
    name string // name of the object
    value int // its value
}

gofmt will line up the columns:

gofmt 会将注释对齐：

type T struct {
    name    string // name of the object
    value   int    // its value
}

All Go code in the standard packages has been formatted with gofmt.

Some formatting details remain. Very briefly:

Indentation We use tabs for indentation and gofmt emits them by default. Use spaces only if you must. Line length Go has no line length limit. Don't worry about overflowing a punched card. If a line feels too long, wrap it and indent with an extra tab. Parentheses Go needs fewer parentheses than C and Java: control structures (if, for, switch) do not have parentheses in their syntax. Also, the operator precedence hierarchy is shorter and clearer, so x<<8 + y<<16 means what the spacing implies, unlike in the other languages.

所有 Go 标准库代码都已使用 gofmt 格式化。

某些格式化的细节依旧非常简明扼要：

缩进

​ 我们使用 tab 进行缩进，默认情况下由 gofmt 负责处理。你只有在必须使用空格的地方使用空格。

行长

​ Go 并没有限制行的长度。别担心会超出穿孔卡~如果你觉得行太长，那就另起一行并使用 tab 来缩进。

圆括弧

​ 相比 C 和 Java，go 使用的括弧更少：控制结构（if,for,switch）在语法上不需要括弧。而且，Go 操作符优先级更加简短明了，例如：

x<<8 + y<<16

空格即表明了优先级，这一点与其它语言不同。（译注：算数操作符 + 优先级要高于移位操作符 <<，但这里的空格改变了因优先级决定的计算顺序）

03.Commentary

Go provides C-style / / block comments and C++-style // line comments. Line comments are the norm; block comments appear mostly as package comments, but are useful within an expression or to disable large swaths of code.

Go 提供 C 风格的块注释 /* */ 和 C++ 风格的行注释 //。我们的准则是使用行注释，块注释主要出现在包的注释当中，但是在注释大段代码或者表达式中亦有用武之地。

The program—and web server—godoc processes Go source files to extract documentation about the contents of the package. Comments that appear before top-level declarations, with no intervening newlines, are extracted along with the declaration to serve as explanatory text for the item. The nature and style of these comments determine the quality of the documentation godoc produces.

godoc 程序（同时也是个 web server）会从 Go 源代码中提取注释作为 package 的文档。那些出现在顶层声明之前，且中间没有换行的注释会被摘录作为该声明项的解释性文字。这些注释的品质和风格将直接关系到 godoc 生成的文档质量。

Every package should have a package comment, a block comment preceding the package clause. For multi-file packages, the package comment only needs to be present in one file, and any one will do. The package comment should introduce the package and provide information relevant to the package as a whole. It will appear first on the godoc page and should set up the detailed documentation that follows.

每一个 package 都应有一个包级块注释，置于 package 语句之前。对于有多个文件的 package，包级注释仅需在其中任意一个文件中呈现。package 注释应概括性的阐述该 package 提供的相关功能特性。它将出现在 godoc 文档页的开头，并引出后面一切详尽的内容。

/*
Package regexp implements a simple library for regular expressions.

The syntax of the regular expressions accepted is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp

If the package is simple, the package comment can be brief.

如果 package 非常简单，那么 package 的注释也可以非常简短。

// Package path implements utility routines for
// manipulating slash-separated filename paths.

Comments do not need extra formatting such as banners of stars. The generated output may not even be presented in a fixed-width font, so don't depend on spacing for alignment—godoc, like gofmt, takes care of that. The comments are uninterpreted plain text, so HTML and other annotations such as _this_ will reproduce verbatim and should not be used. One adjustment godoc does do is to display indented text in a fixed-width font, suitable for program snippets. The package comment for the fmt package uses this to good effect.

注释不需要额外的格式，例如星号组成的 banner。最终显示甚至都不会以固定宽度的字体来呈现，所以不要依赖间距对齐，godoc、gofmt 这些工具会来处理。注释是见文知意的文本，不会再被解析，因此像 HTML 或者类似 _this_ 这样的注解会被逐字复制，因此要避免使用。然而为了更好的显示程序代码片段，godoc 做了一个例外的调整——以固定宽度的字体显示预期文本。fmt 包就是一个很好的示例。

Depending on the context, godoc might not even reformat comments, so make sure they look good straight up: use correct spelling, punctuation, and sentence structure, fold long lines, and so on.

视情形而定，godoc 也许不会重新格式化我们的注释，有鉴于此，我们应尽量让这些注释看起来完美：使用正确的拼写和标点符号，恰当的句式结构，折叠过长的行等等。

Inside a package, any comment immediately preceding a top-level declaration serves as a doc comment for that declaration. Every exported (capitalized) name in a program should have a doc comment.

在 package 内部，任何紧邻顶级声明之前的注释都会被视为该声明的文档。在程序中，每个被导出的项都应有相应的文档注释。

Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.

完整的语句可以让文档注释大放异彩，因为这将造就一个五彩纷呈的自动化呈现。文档的第一句话应以该声明项的名称开头，并且具有概括性。

// Compile parses a regular expression and returns, if successful,
// a Regexp that can be used to match against text.
func Compile(str string) (*Regexp, error) {

If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep. Imagine you couldn't remember the name "Compile" but were looking for the parsing function for regular expressions, so you ran the command,

go doc -all regexp | grep -i parse

If all the doc comments in the package began, "This function...", grep wouldn't help you remember the name. But because the package starts each doc comment with the name, you'd see something like this, which recalls the word you're looking for.

$ go doc -all regexp | grep -i parse
    Compile parses a regular expression and returns, if successful, a Regexp
    MustCompile is like Compile but panics if the expression cannot be parsed.
    parsed. It simplifies safe initialization of global variables holding
$

如果每个文档注释都以它描述的对象名称开头，那么你就可以使用 go 工具链当中的 doc 子命令来过滤你想要的内容。假设你不记得 Compile 方法的名字了，但你清楚你正在寻找一个解析正则表达式的函数，那么你就可以运行如下命令：

go doc -all regexp | grep -i parse

如果注释是以"This function..."开头的，这将对我们毫无帮助，我们依然无法知晓函数的名字。正是因为提倡注释以声明项的名称开始，因此你将会过滤出如下内容，这样一目了然，自然就能回忆起函数的名字来了。

$ go doc -all regexp | grep -i parse
    Compile parses a regular expression and returns, if successful, a Regexp
    MustCompile is like Compile but panics if the expression cannot be parsed.
    parsed. It simplifies safe initialization of global variables holding
$

Go's declaration syntax allows grouping of declarations. A single doc comment can introduce a group of related constants or variables. Since the whole declaration is presented, such a comment can often be perfunctory.

Go 允许组合声明，单一的注释可以用来解释一组常量或者变量。因为要呈现整个组合的说明，所以此类注释通常比较笼统。

// Error codes returned by failures to parse an expression.
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

Grouping can also indicate relationships between items, such as the fact that a set of variables is protected by a mutex.

组合声明也能体现出各项之间的关系，比如下面的例子表明这一组变量集合都被一个 mutex 保护着。

var (
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
    errorCount  uint32
)

04.Names 名称

Names are as important in Go as in any other language. They even have semantic effect: the visibility of a name outside a package is determined by whether its first character is upper case. It's therefore worth spending a little time talking about naming conventions in Go programs.

同其他编程语言一样，名称在 Go 语言中举足轻重，甚至具有语义上的影响：包内名称首字母的大小写会影响到其包外的可见性。因此，花费一点时间来讨论 Go 语言中的命名惯例是很有必要的。

Package names

When a package is imported, the package name becomes an accessor for the contents. After

import "bytes"

the importing package can talk about bytes.Buffer. It's helpful if everyone using the package can use the same name to refer to its contents, which implies that the package name should be good: short, concise, evocative. By convention, packages are given lower case, single-word names; there should be no need for underscores or mixedCaps. Err on the side of brevity, since everyone using your package will be typing that name. And don't worry about collisions a priori. The package name is only the default name for imports; it need not be unique across all source code, and in the rare case of a collision the importing package can choose a different name to use locally. In any case, confusion is rare because the file name in the import determines just which package is being used.

包被导入之后，其名称就成为包中内容的访问器。像 import "bytes" 这样导入 bytes 包之后，就可以使用类似 bytes.Buffer 的方式来访问包中内容了。如果每个使用包的人都采用同样的名称来引用包中内容的话，这无疑是一件大有裨益的事，但这意味着包应该有个合乎时宜的名字：短小精悍，简洁明了，且利于记诵。依照惯例，包名应该采用小写，单字；而且没有必要使用下划线或者混合大小写。一切皆从简，因为每个使用包的人都会输入这个名称。不要在理论上担心这会引起冲突。默认情况下，包在导入时其名称为访问器的名称，但并不是说包的名称要在整个源码中保持唯一；同时导入相同名称的包是非常罕见的，这种情况下我们可以局部地设置一个不一样的名称。不管怎样，导入文件的路径名决定了哪个包将被使用，故不致混淆。

Another convention is that the package name is the base name of its source directory; the package in src/encoding/base64 is imported as "encoding/base64" but has name base64, not encoding_base64 and not encodingBase64.

另一个惯例，包名是其源码目录的 basename; 例如 位于 src/encoding/base64 目录中的包以 "encoding/base64" 的形式被导入，包名为 base64，而不是 encoding_base64，也不是 encodingBase64。

The importer of a package will use the name to refer to its contents, so exported names in the package can use that fact to avoid repetition. (Don't use the import . notation, which can simplify tests that must run outside the package they are testing, but should otherwise be avoided.) For instance, the buffered reader type in the bufio package is called Reader, not BufReader, because users see it as bufio.Reader, which is a clear, concise name. Moreover, because imported entities are always addressed with their package name, bufio.Reader does not conflict with io.Reader. Similarly, the function to make new instances of ring.Ring—which is the definition of a constructor in Go—would normally be called NewRing, but since Ring is the only type exported by the package, and since the package is called ring, it's called just New, which clients of the package see as ring.New. Use the package structure to help you choose good names.

导入者使用包的名称访问其内容，因此包中导出的名称可以利用这一点来避免一些重复。（不要使用 import .，即便这会简化那些必须在包外运行的测试，不过，除此之外应避免使用）例如，bufio 包中带缓冲的 reader 类型名为 Reader，而不是 BufReader，因为使用者将其视作 bufio.Reader，这无疑是一个清晰简洁的名字。此外，被导入者在使用时都会冠以包名，故 bufio.Reader 不会与 io.Reader 冲突。类似地，创建 ring.Ring （Go 标准库中的一个容器）实例的方法通常会被起名为 NewRing ，但是 Ring 是该包中唯一的导出类型，加之包名为 ring ，因此方法可仅作 New ，使用时即是 ring.New。利用包的这种精心安排来助你取个好名字吧。

Another short example is once.Do; once.Do(setup) reads well and would not be improved by writing once.DoOrWaitUntilDone(setup). Long names don't automatically make things more readable. A helpful doc comment can often be more valuable than an extra long name.

另一个简短的例子是 once.Do ，once.Do（setup） 拥有很好的可读性，改为 once.DoOrWaitUntilDone（setup）并不会有所改善。较长的名字并不会提高可读性，一段有益的文档注释往往要比一个额外的冗长名称更具价值。

Getters

Go doesn't provide automatic support for getters and setters. There's nothing wrong with providing getters and setters yourself, and it's often appropriate to do so, but it's neither idiomatic nor necessary to put Get into the getter's name. If you have a field called owner (lower case, unexported), the getter method should be called Owner (upper case, exported), not GetOwner. The use of upper-case names for export provides the hook to discriminate the field from the method. A setter function, if needed, will likely be called SetOwner. Both names read well in practice:

Go 没有自动支持 getter 和 setter 。当然，你自己实现也没有什么不妥，通常情况下理应如此，但在 getter 的名字上加入 Get 既不地道也没必要。如果你有一个名为 owner 的字段（小写，未导出），那么 getter 应该命名为 Owner（大写，导出），而不是 GetOwner。使用大写名称向外暴露内容有助于我们辨别字段和方法。如果确实需要 setter 方法，尽可能命名为 SetOwner。实践证明，这种命名方式工作良好。

owner := obj.Owner()
if owner != user {
    obj.SetOwner(user)
}

Interface names

By convention, one-method interfaces are named by the method name plus an -er suffix or similar modification to construct an agent noun: Reader, Writer, Formatter, CloseNotifier etc.

按照惯例，仅有一个方法的接口要以方法名添加 -er 的后缀来命名，或者通过类似的修改来构造一个施动名词：Reader，Writer，Formatter，CloseNotifier 等等

There are a number of such names and it's productive to honor them and the function names they capture. Read, Write, Close, Flush, String and so on have canonical signatures and meanings. To avoid confusion, don't give your method one of those names unless it has the same signature and meaning. Conversely, if your type implements a method with the same meaning as a method on a well-known type, give it the same name and signature; call your string-converter method String not ToString.

有这么一些名字，它们已然被采用，具有公认的签名和意义，例如：Read, Write, Close, Flush, String 等等。对于这些名字，我们最好给予尊重，除非与其具有相同的签名和意义，否则不要使用，以避免造成混淆。反之，如果你的类型方法和知名类型的方法意思相同，此时当采取相同的方法签名；比如，字符串转换函数需命名为 String 而不是 ToString 。

MixedCaps

Finally, the convention in Go is to use MixedCaps or mixedCaps rather than underscores to write multiword names.

最后，Go 惯于采用驼峰法（CamelCase）书写多字名称，而不是蛇形法（snake_case）。

05.Semicolons 分号

Like C, Go's formal grammar uses semicolons to terminate statements, but unlike in C, those semicolons do not appear in the source. Instead the lexer uses a simple rule to insert semicolons automatically as it scans, so the input text is mostly free of them.

和 C 语言一样，Go 的正式语法使用分号作为语句的结束，但与 C 不同的是，这些分号不需要出现在源码中。而是由词法分析器在扫描源码时，根据一条简单的规则自动地插入，从而解放输入。

The rule is this. If the last token before a newline is an identifier (which includes words like int and float64), a basic literal such as a number or string constant, or one of the tokens

规则如下：如果新行之前的最后一个符号是一个标识符（像 int、float64 这样的词），基本的字面常量（如 number、string），或者如下符号之一

break continue fallthrough return ++ -- ) }

the lexer always inserts a semicolon after the token. This could be summarized as, “if the newline comes after a token that could end a statement, insert a semicolon”.

词法分析器总是会在这些符号后面插入一个分号。一言以蔽之：“如果新行之前的符号可以结束一条语句，那么久插入一个分号”。

A semicolon can also be omitted immediately before a closing brace, so a statement such as

紧邻右大括号之前的分号可以省略，所以下面一条语句不需要分号。

go func() { for { dst <- <-src } }()

needs no semicolons. Idiomatic Go programs have semicolons only in places such as for loop clauses, to separate the initializer, condition, and continuation elements. They are also necessary to separate multiple statements on a line, should you write code that way.

地道的 Go 程序仅在 for 循环中使用分号，用于分隔初始化，条件，continuation 等元素。分号也用于分隔一行中的多个语句，如果你非要那样写的话。

译注：此句“They are also necessary to separate multiple statements on a line, should you write code that way.”为虚拟语气，指将来可能发生的情况，这里的条件句“should you write code that way”放在了主句之后，且省略了连词，并使用了倒装，不易理解；改写一下的话，大致相当于：

Suppose you should write code in the way of putting multiple statements on a line, the semicolons are also necessary here.

但是这个主句中没有情态动词，不知是我理解有误还是原文句法本身不够标准。

One consequence of the semicolon insertion rules is that you cannot put the opening brace of a control structure (if, for, switch, or select) on the next line. If you do, a semicolon will be inserted before the brace, which could cause unwanted effects. Write them like this

分号插入规则的一个后果就是，你不能把控制语句（if, for, switch, or select）的左大括号放到新行上。如果你那样做，左大括号之前会被插入一个分号，这将导致编译错误，比如你应该这样写

if i < f() {
    g()
}

not like this

而不是这样写

if i < f()  // wrong!
{           // wrong!
    g()
}

06.Control structures 控制结构

The control structures of Go are related to those of C but differ in important ways. There is no do or while loop, only a slightly generalized for; switch is more flexible; if and switch accept an optional initialization statement like that of for; break and continue statements take an optional label to identify what to break or continue; and there are new control structures including a type switch and a multiway communications multiplexer, select. The syntax is also slightly different: there are no parentheses and the bodies must always be brace-delimited.

Go 中的控制结构和 C 有一定的相关性，但在一些重要方面有所不同。Go 没有 do 或者 while 循环，只靠一个 for 走天下；switch 则更加灵活；类似于 for，if 和 switch 都接受一个可选的初始化语句；break 和 continue 可以跟一个可选标签来表示跳出和继续的对象；还有，Go 拥有新的控制结构，包扩 type switch 和多路通信复用 select 。语法也有些许变化：没有圆括号、控制体必须要置于大括号之内。

If

In Go a simple if looks like this:

下面是 Go 中的一个简单的 if ：

if x > 0 {
    return y
}

Mandatory braces encourage writing simple if statements on multiple lines. It's good style to do so anyway, especially when the body contains a control statement such as a return or break

强制使用大括号，以此鼓励编写多行简单的 if 语句。总之，这是一种良好的代码风格，尤其是 body 中包含诸如 return、break 等控制结构的时候。

Since if and switch accept an initialization statement, it's common to see one used to set up a local variable.

正是因为 if 和 switch 都能使用初始化语句，所以经常会看到如下设置本地变量的用法。

if err := file.Chmod(0664); err != nil {
    log.Print(err)
    return err
}

In the Go libraries, you'll find that when an if statement doesn't flow into the next statement—that is, the body ends in break, continue, goto, or return—the unnecessary else is omitted.

在 Go 的标准库中，你会发现，当一个 if 语句成为终结者的时候—意为：body 以 break，continue，goto，或 return 结束，此时会省略已经没必要的 else。

f, err := os.Open(name)
if err != nil {
    return err
}
codeUsing(f)

This is an example of a common situation where code must guard against a sequence of error conditions. The code reads well if the successful flow of control runs down the page, eliminating error cases as they arise. Since error cases tend to end in return statements, the resulting code needs no else statements.

下面的示例涉及到一个非常普遍的情况，代码必须防范一连串的错误情况。如果语句成功则向下执行，遇到错误则处理错误，代码就具有高可读性。由于错误情况的处理往往以 return 语句结束，所以代码不需要 else 语句。

f, err := os.Open(name)
if err != nil {
    return err
}
d, err := f.Stat()
if err != nil {
    f.Close()
    return err
}
codeUsing(f, d)

Redeclaration and reassignment

重新声明与重新赋值

An aside: The last example in the previous section demonstrates a detail of how the := short declaration form works. The declaration that calls os.Open reads,

题外话：上个示例展示了短变量声明 “:=” 的用法，即 os.Open 的调用声明，

f, err := os.Open(name)

This statement declares two variables, f and err. A few lines later, the call to f.Stat reads,

此句声明了两个变量，f 和 err，并在稍后调用了 f.Stat,

d, err := f.Stat()

which looks as if it declares d and err. Notice, though, that err appears in both statements. This duplication is legal: err is declared by the first statement, but only re-assigned in the second. This means that the call to f.Stat uses the existing err variable declared above, and just gives it a new value.

这句看起来像是声明了 d 和 err。注意看，虽然两个语句都出现了 err，但这样做完全合法：第一个语句声明 err，第二个语句仅仅重新赋值。意味着 f.Stat 调用使用之前声明的 err 变量，只是给予其一个新值。

In a := declaration a variable v may appear even if it has already been declared, provided:

在 := 短变量声明中，变量 v 可以是已声明的，只需满足如下条件：

• this declaration is in the same scope as the existing declaration of v (if v is already declared in an outer scope, the declaration will create a new variable §),

• the corresponding value in the initialization is assignable to v, and

• there is at least one other variable that is created by the declaration.

• 已声明的 v 需和本次声明位于相同作用域（如果外层作用域已有 v 的声明，那么本次声明会创建一个新的变量）

• 赋值需与 v 的类型一致

• 至少要在本次声明中创建一个新的变量

This unusual property is pure pragmatism, making it easy to use a single err value, for example, in a long if-else chain. You'll see it used often.

在长长的 if-else 链中使用唯一的 err 变得易如反掌，这种非比寻常的特性非常实用。你会经常看到这种用法。

It's worth noting here that in Go the scope of function parameters and return values is the same as the function body, even though they appear lexically outside the braces that enclose the body.

这里值得注意的是，在 Go 中，函数参数和返回值的范围与函数体相同，即使它们在词法上位于函数体的大括号之外。

For

The Go for loop is similar to—but not the same as—C's. It unifies for and while and there is no do-while. There are three forms, only one of which has semicolons.

Go 的 for 循环类似于 C 但又不同于 C。它统一了 for 和 while，并且没有 do-while 循环。for 循环有三种形式，只有其中一个需要分号。

// Like a C for
for init; condition; post { }

// Like a C while
for condition { }

// Like a C for(;;)
for { }

Short declarations make it easy to declare the index variable right in the loop.

短变量声明使得在循环中声明索引变量非常容易。

sum := 0
for i := 0; i < 10; i++ {
    sum += i
}

If you're looping over an array, slice, string, or map, or reading from a channel, a range clause can manage the loop.

如需循环遍历 array，slice，string，or map，或者从一个 channel 读取数据，则可以使用 range 字句。

for key, value := range oldMap {
    newMap[key] = value
}

If you only need the first item in the range (the key or index), drop the second:

在 range 时，若只需要第一项（the key or index），则省略第二项：

for key := range m {
    if key.expired() {
        delete(m, key)
    }
}

If you only need the second item in the range (the value), use the blank identifier, an underscore, to discard the first:

若只需要第二项，可以使用空标识符（下划线）表示丢弃该值：

sum := 0
for _, value := range array {
    sum += value
}

The blank identifier has many uses, as described in a later section.

空标识符有很多妙用，后面的章节会详细介绍。

For strings, the range does more work for you, breaking out individual Unicode code points by parsing the UTF-8. Erroneous encodings consume one byte and produce the replacement rune U+FFFD. (The name (with associated builtin type) rune is Go terminology for a single Unicode code point. See the language specification for details.) The loop

对于字符串来讲，range 会替你做更多的工作—隐式地按 UTF-8 解码。错误的编码会消耗掉一个字节，并使用 U+FFFD 作为替代 rune。rune 是 Go 中的一个术语，它是一个内建类型，代表一个 Unicode 码点（详见 the language specification），循环

for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding
    fmt.Printf("character %#U starts at byte position %d\n", char, pos)
}

prints

会打印出

character U+65E5 '日' starts at byte position 0
character U+672C '本' starts at byte position 3
character U+FFFD '�' starts at byte position 6
character U+8A9E '語' starts at byte position 7

Finally, Go has no comma operator and ++ and -- are statements not expressions. Thus if you want to run multiple variables in a for you should use parallel assignment (although that precludes ++ and --).

最后，Go 没有逗号运算符，++ 和 -- 是语句而非表达式。因此，如果你想在 for 循环中对多个变量进行运算，那么你应该使用并行赋值（尽管这样没法使用 ++ 和 --）。

译注：C 语言中有逗号运算符，++ 和 -- 是表达式，因此可以这样写

for (int i = 0, j = len(a)-1; i < j; i++, j--) {
  //
}

注意下面 Go 语言 for 循环的条件 i, j = i+1, j-1，这是作者意之所在。

// Reverse a
for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
    a[i], a[j] = a[j], a[i]
}

Switch

Go's switch is more general than C's. The expressions need not be constants or even integers, the cases are evaluated top to bottom until a match is found, and if the switch has no expression it switches on true. It's therefore possible—and idiomatic—to write an if-else-if-else chain as a switch.

Go 的 switch 在功能上要比 C 更加广泛。其表达式不拘于常量或者整数，分支自顶向下求值，直至遇到匹配项，而且如果 switch 没有表达式，则分支以 true 为条件进行求值。因此在 Go 中可以使用 switch 来代替 if-else-if-else 链，实际上使用 switch 更加地道。

func unhex(c byte) byte {
    switch {
    case '0' <= c && c <= '9':
        return c - '0'
    case 'a' <= c && c <= 'f':
        return c - 'a' + 10
    case 'A' <= c && c <= 'F':
        return c - 'A' + 10
    }
    return 0
}

There is no automatic fall through, but cases can be presented in comma-separated lists.

Go 并不会自动 fallthrough 去执行下一个分支（译注：Go 中 switch 的 fallthrough 可以强制执行后面的 case ），但是可以在 case 中使用逗号分隔多个匹配项。

func shouldEscape(c byte) bool {
    switch c {
    case ' ', '?', '&', '=', '#', '+', '%':
        return true
    }
    return false
}

Although they are not nearly as common in Go as some other C-like languages, break statements can be used to terminate a switch early. Sometimes, though, it's necessary to break out of a surrounding loop, not the switch, and in Go that can be accomplished by putting a label on the loop and "breaking" to that label. This example shows both uses.

在 Go 中可以用 break 语句提前结束 switch，尽管这在其它类 C 语言中没那么常见。然而有时候代码需要跳出外层循环而不是默认的 switch，这时就可以在循环的位置添加一个 label，并在 breake 时指定这个 label 即可，下面的示例同时展示了这两种用法：

Loop:
 for n := 0; n < len(src); n += size {
  switch {
  case src[n] < sizeOne:
   if validateOnly {
    break
   }
   size = 1
   update(src[n])

  case src[n] < sizeTwo:
   if n+1 >= len(src) {
    err = errShortInput
    break Loop
   }
   if validateOnly {
    break
   }
   size = 2
   update(src[n] + src[n+1]<<shift)
  }
 }

Of course, the continue statement also accepts an optional label but it applies only to loops.

当然，continue 语句也可以指定 label，但这仅仅在循环中适用。

To close this section, here's a comparison routine for byte slices that uses two switch statements:

我们用一个比较两个 slice 的例程来结束这一小节，这个例程使用了两个 switch：

// Compare returns an integer comparing the two byte slices,
// lexicographically.
// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
func Compare(a, b []byte) int {
    for i := 0; i < len(a) && i < len(b); i++ {
        switch {
        case a[i] > b[i]:
            return 1
        case a[i] < b[i]:
            return -1
        }
    }
    switch {
    case len(a) > len(b):
        return 1
    case len(a) < len(b):
        return -1
    }
    return 0
}

Type switch

A switch can also be used to discover the dynamic type of an interface variable. Such a type switch uses the syntax of a type assertion with the keyword type inside the parentheses. If the switch declares a variable in the expression, the variable will have the corresponding type in each clause. It's also idiomatic to reuse the name in such cases, in effect declaring a new variable with the same name but a different type in each case.

switch 还可以用来识别一个接口变量的动态类型。它使用类型断言的语法，将关键字 type 放在一对括号内。如果在表达式中声明了变量，那么这个变量就会拥有与每个 case 相对应的类型。这种情况下，重用变量名也是一种地道用法，事实上，虽然使用相同的名称声明新变量，但变量在每个 case 中都有不同的类型。

var t interface{}
t = functionOfSomeType()
switch t := t.(type) {
default:
    fmt.Printf("unexpected type %T\n", t)     // %T prints whatever type t has
case bool:
    fmt.Printf("boolean %t\n", t)             // t has type bool
case int:
    fmt.Printf("integer %d\n", t)             // t has type int
case *bool:
    fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool
case *int:
    fmt.Printf("pointer to integer %d\n", *t) // t has type *int
}

07.Functions 函数

Multiple return values

One of Go's unusual features is that functions and methods can return multiple values. This form can be used to improve on a couple of clumsy idioms in C programs: in-band error returns such as -1 for EOF and modifying an argument passed by address.

函数和方法具有多个返回值是 Go 的特性之一，此特性可在很大程度上矫正 C 语言一些笨拙的编码风格：带内错误返回值，例如用 -1 表示 EOF ，还有通过传址修改参数。

译注：带内（in-band）和带外（out-of-band）是通讯领域的概念，《UNIX 网络编程》卷一第 24 章有关于带外数据的描述，带内数据资料甚少，有熟悉的朋友可以提供一下，另 Error Handling 一文高屋建瓴，立意颇深，有兴趣的读者可以一观。

In C, a write error is signaled by a negative count with the error code secreted away in a volatile location. In Go, Write can return a count and an error: “Yes, you wrote some bytes but not all of them because you filled the device”. The signature of the Write method on files from package os is:

在 C 中，通过一个负的写入数量来表示 write 发生错误 ，而且其错误码隐藏在一个很不稳定的位置（译注：这里指 errno 是一个全局变量，errno 的值只有在一个库函数调用发生错误时才会被设置，当库函数调用成功运行时，errno 的值不会被修改，当然也不会主动被置为 0）。在 Go 中，Write 可以同时返回写入数量和一个 error：“没错，因为磁盘爆满，并非所有的字节都被成功写入”。os 包中关于 file 的写入函数签名为：

func (file *File) Write(b []byte) (n int, err error)

and as the documentation says, it returns the number of bytes written and a non-nil error when n != len(b). This is a common style; see the section on error handling for more examples.

正如文档所示，当 n != len(b) 时，它返回已写入的字节数和一个非 nil 的 error。这是一种常见风格，更多示例见错误处理章节。

A similar approach obviates the need to pass a pointer to a return value to simulate a reference parameter. Here's a simple-minded function to grab a number from a position in a byte slice, returning the number and the next position.

这种多返回值的方式，不再需要传递一个指针，不再需要把返回值伪装成一个引用参数。这里有一个用于从字节切片特定位置提取数字并返回该数字和下一个位置的函数，它的实现非常朴实无华：

func nextInt(b []byte, i int) (int, int) {
    for ; i < len(b) && !isDigit(b[i]); i++ {
    }
    x := 0
    for ; i < len(b) && isDigit(b[i]); i++ {
        x = x*10 + int(b[i]) - '0'
    }
    return x, i
}

You could use it to scan the numbers in an input slice b like this:

你可以使用它从切片 b 扫描数字，就像这样：

for i := 0; i < len(b); {
    x, i = nextInt(b, i)
    fmt.Println(x)
}

Named result parameters

The return or result "parameters" of a Go function can be given names and used as regular variables, just like the incoming parameters. When named, they are initialized to the zero values for their types when the function begins; if the function executes a return statement with no arguments, the current values of the result parameters are used as the returned values.

Go 函数的返回参数可以被命名，且可以像入参一样当做常规变量来使用。一旦被命名，它们将在函数开始时被初始化为相应类型的零值；如果此函数的 return 语句没有施加参数，则被命名的当前结果参数值将被当作返回值返回。

The names are not mandatory but they can make code shorter and clearer: they're documentation. If we name the results of nextInt it becomes obvious which returned int is which.

对返回参数命名并非强制性的，但这样做可以使代码更加简短：因为他们是自解释的。假使我们对返回值 nextInt 进行命名，那么返回的 int 是哪一个将一目了然。

func nextInt(b []byte, pos int) (value, nextPos int) {

Because named results are initialized and tied to an unadorned return, they can simplify as well as clarify. Here's a version of io.ReadFull that uses them well:

因为命名的结果值会被初始化，而且在函数中使用 return 不再需要追加参数，如此则非常简洁明白。这里有一个 io.ReadFull 函数的使用范例：

func ReadFull(r Reader, buf []byte) (n int, err error) {
    for len(buf) > 0 && err == nil {
        var nr int
        nr, err = r.Read(buf)
        n += nr
        buf = buf[nr:]
    }
    return
}

Defer

Go's defer statement schedules a function call (the deferred function) to be run immediately before the function executing the defer returns. It's an unusual but effective way to deal with situations such as resources that must be released regardless of which path a function takes to return. The canonical examples are unlocking a mutex or closing a file.

Go 的 defer 语句会安排一个函数调用（被延期的），执行 defer 的函数退出之际会调用这个被排定的函数。这是一种与众不同却很有效的方式，特别是在处理一些需要释放资源的情况时，无论函数在何种路径下退出，都要进行妥善处理。典型的例子有释放锁或者关闭一个文件。

// Contents returns the file's contents as a string.
func Contents(filename string) (string, error) {
    f, err := os.Open(filename)
    if err != nil {
        return "", err
    }
    defer f.Close()  // f.Close will run when we're finished.

    var result []byte
    buf := make([]byte, 100)
    for {
        n, err := f.Read(buf[0:])
        result = append(result, buf[0:n]...) // append is discussed later.
        if err != nil {
            if err == io.EOF {
                break
            }
            return "", err  // f will be closed if we return here.
        }
    }
    return string(result), nil // f will be closed if we return here.
}

Deferring a call to a function such as Close has two advantages. First, it guarantees that you will never forget to close the file, a mistake that's easy to make if you later edit the function to add a new return path. Second, it means that the close sits near the open, which is much clearer than placing it at the end of the function.

以 Close 为例，把一个函数调用延期执行有两点好处。第一，保证你永远不会忘记关闭文件，尤其是后期修改函数增加新的 return 路径时。第二，使用 defer 意味着 Close 函数与 Open 函数邻近，这比写在函数末尾要清晰得多。

The arguments to the deferred function (which include the receiver if the function is a method) are evaluated when the defer executes, not when the call executes. Besides avoiding worries about variables changing values as the function executes, this means that a single deferred call site can defer multiple function executions. Here's a silly example.

延期函数的参数（如果函数是方法，也包括其接收器）会在 defer 语句执行那一刻求值，并非是函数执行那一刻。这意味着一个 defer 语句可以延迟多个函数执行，而且还不用担心变量在执行时改变。这里有一个略蠢的例子。

for i := 0; i < 5; i++ {
    defer fmt.Printf("%d ", i)
}

Deferred functions are executed in LIFO order, so this code will cause 4 3 2 1 0 to be printed when the function returns. A more plausible example is a simple way to trace function execution through the program. We could write a couple of simple tracing routines like this:

被 defer 的函数按后进先出的顺序执行，故这段代码会依次打印 4 3 2 1 0 。一个更加合理的例子是简易函数追踪。我们可以写几个简单的追踪例程：

func trace(s string)   { fmt.Println("entering:", s) }
func untrace(s string) { fmt.Println("leaving:", s) }

// Use them like this:
func a() {
    trace("a")
    defer untrace("a")
    // do something....
}

We can do better by exploiting the fact that arguments to deferred functions are evaluated when the defer executes. The tracing routine can set up the argument to the untracing routine. This example:

利用函数参数会在 defer 时被求值这一事实，我们可以进一步完善追踪程序。tracing 例程可以设置参数到 untracing 例程。示例如下：

func trace(s string) string {
    fmt.Println("entering:", s)
    return s
}

func un(s string) {
    fmt.Println("leaving:", s)
}

func a() {
    defer un(trace("a"))
    fmt.Println("in a")
}

func b() {
    defer un(trace("b"))
    fmt.Println("in b")
    a()
}

func main() {
    b()
}

prints

打印

entering: b
in b
entering: a
in a
leaving: a
leaving: b

For programmers accustomed to block-level resource management from other languages, defer may seem peculiar, but its most interesting and powerful applications come precisely from the fact that it's not block-based but function-based. In the section on panic and recover we'll see another example of its possibilities.

对习惯于其它编程语言中 block-level 资源管理的开发者来说，defer 稍显怪异，但其最引人入胜、最强大的应用正是来自于它是 function-based 而不是 block-based 这一事实。我们将会在 panic 和 recover 章节探索 defer 其它可能的用法。

08.Data 数据

Allocation with new

Go has two allocation primitives, the built-in functions new and make. They do different things and apply to different types, which can be confusing, but the rules are simple. Let's talk about new first. It's a built-in function that allocates memory, but unlike its namesakes in some other languages it does not initialize the memory, it only zeros it. That is, new(T) allocates zeroed storage for a new item of type T and returns its address, a value of type *T. In Go terminology, it returns a pointer to a newly allocated zero value of type T.

Go 有两个分配内存的原语，分别是内建函数 new 和 make。它们职责不同，适用于不同的类型，这可能带有迷惑性，但其实规则非常简单。我们先来讨论 new。new 是一个分配内存的内建函数，然而不同于其它语言中的同名函数，它并不初始化内存，仅在内存存储 type 的零值。即 new(T) 为类型 T 分配一个存储零值的内存项并返回它的地址，也就是一个类型为 *T 的值。以 Go 的术语来讲，它返回的是一个新分配的类型为 T 的零值的指针。

Since the memory returned by new is zeroed, it's helpful to arrange when designing your data structures that the zero value of each type can be used without further initialization. This means a user of the data structure can create one with new and get right to work. For example, the documentation for bytes.Buffer states that "the zero value for Buffer is an empty buffer ready to use." Similarly, sync.Mutex does not have an explicit constructor or Init method. Instead, the zero value for a sync.Mutex is defined to be an unlocked mutex.

因为 new 返回的内存是相应类型的零值，所以在设计数据结构的时候，使每个类型的零值在无需初始化的情况下能直接被使用，是非常有益的。这意味着用户可以使用 new 创建一个开箱即用的数据结构。例如，bytes.Buffer 的文档表明：“Buffer 的零值是一个开箱即用的空 buffer”。同样，sync.Mutex 并没有显式的构造器或者 Init 方法。而是将其零值定义为一个未上锁的 mutex。

The zero-value-is-useful property works transitively. Consider this type declaration.

“零值可用”具有传递性，考虑如下类型声明。

type SyncedBuffer struct {
    lock    sync.Mutex
    buffer  bytes.Buffer
}

Values of type SyncedBuffer are also ready to use immediately upon allocation or just declaration. In the next snippet, both p and v will work correctly without further arrangement.

使用 new 或者 make 创建 SyncedBuffer ，亦或直接声明（使用 var 或短变量）一个 SyncedBuffer 变量，其值同样开箱即用。下面的代码片段中，p 和 v 无需进一步处理即可正常使用。

p := new(SyncedBuffer)  // type *SyncedBuffer
var v SyncedBuffer      // type  SyncedBuffer

Constructors and composite literals

Sometimes the zero value isn't good enough and an initializing constructor is necessary, as in this example derived from package os.

有时仅仅零值并不能满足需求，亟需一个构造器用于初始化，如下来自 os 包中的一个示例。

func NewFile(fd int, name string) *File {
    if fd < 0 {
        return nil
    }
    f := new(File)
    f.fd = fd
    f.name = name
    f.dirinfo = nil
    f.nepipe = 0
    return f
}

There's a lot of boiler plate in there. We can simplify it using a composite literal, which is an expression that creates a new instance each time it is evaluated.

这里充斥着大量的样板代码（译注：指四个赋值语句）。我们可以用复合字面量来简化它，复合字面量是一个表达式，用于在创建实例时一并赋值。

func NewFile(fd int, name string) *File {
    if fd < 0 {
        return nil
    }
    f := File{fd, name, nil, 0}
    return &f
}

Note that, unlike in C, it's perfectly OK to return the address of a local variable; the storage associated with the variable survives after the function returns. In fact, taking the address of a composite literal allocates a fresh instance each time it is evaluated, so we can combine these last two lines.

值得注意的是，与 C 语言不同，在函数中返回一个局部变量的指针是完全没问题的；与该变量相关的内存区域在函数返回后并不会被释放。实际上，每次对复合字面量取址时都会生成新的实例，因此我们可以合并最后两行。

return &File{fd, name, nil, 0}

The fields of a composite literal are laid out in order and must all be present. However, by labeling the elements explicitly as field:value pairs, the initializers can appear in any order, with the missing ones left as their respective zero values. Thus we could say

复合字面量需按顺序列出所有的字段。然而，你可以使用键值对的方式来初始化每个字段，这样就无顺序要求，如果省略某个字段，其值为相应类型的零值。所以我们可以这样写：

return &File{fd: fd, name: name}

As a limiting case, if a composite literal contains no fields at all, it creates a zero value for the type. The expressions new(File) and &File{} are equivalent.

极端情况下，复合字面量中没有字段，这样会创建这个类型的零值。new(File) 和 &File{} 是等效的。

Composite literals can also be created for arrays, slices, and maps, with the field labels being indices or map keys as appropriate. In these examples, the initializations work regardless of the values of Enone, Eio, and Einval, as long as they are distinct.

复合字面量亦可用于创建 array、slice 和 map，字段的 label 视情况成为索引或者 map 的 key。在下面的例子中，只要 label 是唯一的，初始化就会成功。

a := [...]string   {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}

Allocation with make

Back to allocation. The built-in function make(T, args) serves a purpose different from new(T). It creates slices, maps, and channels only, and it returns an initialized (not zeroed) value of type T (not *T). The reason for the distinction is that these three types represent, under the covers, references to data structures that must be initialized before use. A slice, for example, is a three-item descriptor containing a pointer to the data (inside an array), the length, and the capacity, and until those items are initialized, the slice is nil. For slices, maps, and channels, make initializes the internal data structure and prepares the value for use. For instance,

言归正传，我们将话题拉回到内存分配。内建函数 make(T, args) 的作用不同于new(T)，make 仅用于创建 slice、map 和 channel，而且它返回的是已经初始化的（不是零值）类型 T 的值，而不是 T 的指针。究其原因，是由于这三种类型其底层是对一些数据结构的引用，而这些数据结构在使用前必须初始化。以 slice 为例，它是一个三项描述符（译注：底层为含有三字段的结构体），包含一个数组指针，长度和容量，除非三项全部初始化，否则 slice 就是 nil 的。对于 slice、map 和 channel，make 会初始化它们内部的数据结构并准备好可用的值。例如：

make([]int, 10, 100)

allocates an array of 100 ints and then creates a slice structure with length 10 and a capacity of 100 pointing at the first 10 elements of the array. (When making a slice, the capacity can be omitted; see the section on slices for more information.) In contrast, new([]int) returns a pointer to a newly allocated, zeroed slice structure, that is, a pointer to a nil slice value.

这条语句会分配含有 100 个 int 的数组，之后创建长度为 10，容量为 100 的 slice 的结构体实例，并指向数组中前 10 个元素。（创建 slice 时，容量可以省略，详见 slice 章节）相反，new([]int) 返回一个新分配的、零值的 slice 结构体指针，这是个指向 nil 的 slice 的指针。

These examples illustrate the difference between new and make.

下面这些示例阐述了 new 和 make 的区别。

var p *[]int = new([]int)       // allocates slice structure; *p == nil; rarely useful
var v  []int = make([]int, 100) // the slice v now refers to a new array of 100 ints

// Unnecessarily complex:
var p *[]int = new([]int)
*p = make([]int, 100, 100)

// Idiomatic:
v := make([]int, 100)

Remember that make applies only to maps, slices and channels and does not return a pointer. To obtain an explicit pointer allocate with new or take the address of a variable explicitly.

记住，make 仅适用于 map，slice 和 channel，而且返回的不是指针。要得到一个指针，请使用 new 或者使用取址符。

Arrays

Arrays are useful when planning the detailed layout of memory and sometimes can help avoid allocation, but primarily they are a building block for slices, the subject of the next section. To lay the foundation for that topic, here are a few words about arrays.

Array 有助于设计精细化的内存布局，而且有时可以避免（频繁地）内存分配，但主要用于构成 slice，slice 是下一章节的主题。为了打好关于 slice 的基础，现就 array 多言几句。

There are major differences between the ways arrays work in Go and C. In Go,

• Arrays are values. Assigning one array to another copies all the elements.
• In particular, if you pass an array to a function, it will receive a copy of the array, not a pointer to it.
• The size of an array is part of its type. The types [10]int and [20]int are distinct.

数组在 Go 和 C 中的工作方式有天壤之别。在 Go 中：

• 数组是值类型。将一个数组赋值给另一个会复制数组中所有元素
• 特别是将数组作为函数参数传递时，函数内部将收到一份数组的 copy， 而不是指针。
• 数组的大小是类型的一部分。[10]int 和 [20]int 是两种不同的类型

The value property can be useful but also expensive; if you want C-like behavior and efficiency, you can pass a pointer to the array.

值类型是有益的，但同时也是昂贵的；如果你想以 C 的方式使用数组，可以传递一个数组的指针。

func Sum(a *[3]float64) (sum float64) {
    for _, v := range *a {
        sum += v
    }
    return
}

array := [...]float64{7.0, 8.5, 9.1}
x := Sum(&array)  // Note the explicit address-of operator

But even this style isn't idiomatic Go. Use slices instead.

但即使这种风格也不是 Go 的惯用手法。请改用 slice。

Slices

Slices wrap arrays to give a more general, powerful, and convenient interface to sequences of data. Except for items with explicit dimension such as transformation matrices, most array programming in Go is done with slices rather than simple arrays.

通过对 array 的封装，slice 为数据序列提供了更加通用、强大和便捷的接口。在 Go 中，除了像转换矩阵这样具有明确维度的项，大多数数组编程都使用 slice 而非简单的 array。

Slices hold references to an underlying array, and if you assign one slice to another, both refer to the same array. If a function takes a slice argument, changes it makes to the elements of the slice will be visible to the caller, analogous to passing a pointer to the underlying array. A Read function can therefore accept a slice argument rather than a pointer and a count; the length within the slice sets an upper limit of how much data to read. Here is the signature of the Read method of the File type in package os:

slice 持有一个底层数组的引用，如果你将一个 slice 赋值给另一个 slice，那么这两个 slice 会指向同一个底层数组。在一个带有 slice 参数的函数中，如果改变了 slice 中的元素，则调用者也会察觉到改变，就好像为函数传入一个数组指针一样。故一个 Read 函数应该接受一个 silce 作为参数，而不是一个指针加一个数量；slice 的长度即规定了数据读取的上限。下面是一个 os 包中 File 类型的 Read 方法签名：

func (f *File) Read(buf []byte) (n int, err error)

The method returns the number of bytes read and an error value, if any. To read into the first 32 bytes of a larger buffer buf, slice (here used as a verb) the buffer.

该方法返回读取的字节数和一个错误（如果有的话）。把 buffer 切开，来读取其前 32 个字节。

n, err := f.Read(buf[0:32])

Such slicing is common and efficient. In fact, leaving efficiency aside for the moment, the following snippet would also read the first 32 bytes of the buffer.

这种切割方式非常常见和高效，事实上，不考虑效率的话，下面的代码片段也具有相同的效果。

var n int
    var err error
    for i := 0; i < 32; i++ {
        nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
        n += nbytes
        if nbytes == 0 || e != nil {
            err = e
            break
        }
    }

The length of a slice may be changed as long as it still fits within the limits of the underlying array; just assign it to a slice of itself. The capacity of a slice, accessible by the built-in function cap, reports the maximum length the slice may assume. Here is a function to append data to a slice. If the data exceeds the capacity, the slice is reallocated. The resulting slice is returned. The function uses the fact that len and cap are legal when applied to the nil slice, and return 0.

只要不超过底层数组的容量，就可将 slice 赋值给它自身来改变其长度。通过内建函数 cap 可访问 slice 的容量，它代表 slice 所能达到的最大长度。下面是一个向 slice 追加数据的函数。如果追加后的数据超出了容量，即会重新分配内存（译注：更换底层数组）。最终结果 slice 会被返回。该函数巧妙地利用了 cap 和 len 在 nil 的 slice 中合法且返回 0 的事实。

func Append(slice, data []byte) []byte {
    l := len(slice)
    if l + len(data) > cap(slice) {  // reallocate
        // Allocate double what's needed, for future growth.
        newSlice := make([]byte, (l+len(data))*2)
        // The copy function is predeclared and works for any slice type.
        copy(newSlice, slice)
        slice = newSlice
    }
    slice = slice[0:l+len(data)]
    copy(slice[l:], data)
    return slice
}

We must return the slice afterwards because, although Append can modify the elements of slice, the slice itself (the run-time data structure holding the pointer, length, and capacity) is passed by value.

随后，我们须将扩充后的 slice 返回。因为，尽管 Append 能够修改 slice 中的元素，但是 slice 本身（持有底层指针，长度和容量的运行时数据结构）却是以值的方式传递进来的。

译注：slice 以传值方式进入函数，因此是一个 slice 的副本，即底层数组指针，长度和容量的 copy。因为指针相同，指向的底层数组也相同，所以改变其值后，原 slice 也会观察到改变；但是，一旦发生扩容，底层的数组即被重新分配，于此在数组层面便与原 slice 分道扬镳了。这就是文中所说要返回追加后的 slice 给调用者，而不是让调用者依赖原 slice 的原因。

The idea of appending to a slice is so useful it's captured by the append built-in function. To understand that function's design, though, we need a little more information, so we'll return to it later.

向 slice 追加数据是一个很常见的操作，因此这一功能已被收录于内建函数中，名为 append。要深入理解其设计思想，我们仍需要一些信息，所以稍后再回到这个话题。

Two-dimensional slices

Go's arrays and slices are one-dimensional. To create the equivalent of a 2D array or slice, it is necessary to define an array-of-arrays or slice-of-slices, like this:

Go 的数组和切片都是一维的。要创建二维模型，你需要定义数组的数组或者切片的切片，就像这样：

type Transform [3][3]float64  // A 3x3 array, really an array of arrays.
type LinesOfText [][]byte     // A slice of byte slices.

Because slices are variable-length, it is possible to have each inner slice be a different length. That can be a common situation, as in our LinesOfText example: each line has an independent length.

得益于切片的变长特性，每个内部的切片可以拥有不同的长度。这种场景非常普遍，正如我们刚刚定义的 LinesOfText：每一行都拥有各自的长度。

text := LinesOfText{
 []byte("Now is the time"),
 []byte("for all good gophers"),
 []byte("to bring some fun to the party."),
}

Sometimes it's necessary to allocate a 2D slice, a situation that can arise when processing scan lines of pixels, for instance. There are two ways to achieve this. One is to allocate each slice independently; the other is to allocate a single array and point the individual slices into it. Which to use depends on your application. If the slices might grow or shrink, they should be allocated independently to avoid overwriting the next line; if not, it can be more efficient to construct the object with a single allocation. For reference, here are sketches of the two methods. First, a line at a time:

有时候使用二维切片是必要的，试想一下处理像素扫描这种场景。有两种方式可以建立二维切片，一种方式是单独分配每个切片；另一种方式是分配一个一维切片（译注：文中 array 意指切片底层是一个数组，相比较而言，第一种方法是单独分配每一行切片，就拥有多个底层数组），然后从中切割出每一行放入顶层切片中（译注：原文未体现顶层切片，意思并不完整）。具体使用哪一种方式取决于你的应用程序。如果切片可能会增长或者收缩，为避免覆盖下一行的数据，请使用单独分配切片的方式；反之，使用一次性分配切的方式会比较高效。为了便于理解，现附上这两种方式的示意代码。首先是每一行分配一个切片：

// Allocate the top-level slice.
picture := make([][]uint8, YSize) // One row per unit of y.
// Loop over the rows, allocating the slice for each row.
for i := range picture {
 picture[i] = make([]uint8, XSize)
}

And now as one allocation, sliced into lines:

接下来是一次性分配，切割出每一行：

// Allocate the top-level slice, the same as before.
picture := make([][]uint8, YSize) // One row per unit of y.
// Allocate one large slice to hold all the pixels.
pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8.
// Loop over the rows, slicing each row from the front of the remaining pixels slice.
for i := range picture {
 picture[i], pixels = pixels[:XSize], pixels[XSize:]
}

Maps

Maps are a convenient and powerful built-in data structure that associate values of one type (the key) with values of another type (the element or value). The key can be of any type for which the equality operator is defined, such as integers, floating point and complex numbers, strings, pointers, interfaces (as long as the dynamic type supports equality), structs and arrays. Slices cannot be used as map keys, because equality is not defined on them. Like slices, maps hold references to an underlying data structure. If you pass a map to a function that changes the contents of the map, the changes will be visible in the caller.

Map 是一种强大便捷的内置数据结构，它将一种类型的值（key）与另一种类型的值关联起来。Key 的类型可以是任意一种支持判等操作的类型，例如 integers， floating point， complex numbers，strings，pointers， interfaces （只要其动态类型支持判等）,structs，arrays 等。Slice 不可以用作 map 的 key，因为其不支持判等操作。与 slice 一样，map 也持有一个底层数据结构的引用。若将 map 传入一个函数，且在函数内部修改了 map 的内容，则变更亦对调用者可见。

Maps can be constructed using the usual composite literal syntax with colon-separated key-value pairs, so it's easy to build them during initialization.

Map 可使用复合字面量方式构建，键值对以冒号分隔，因此可以轻松地初始化一个 map。

var timeZone = map[string]int{
    "UTC":  0*60*60,
    "EST": -5*60*60,
    "CST": -6*60*60,
    "MST": -7*60*60,
    "PST": -8*60*60,
}

Assigning and fetching map values looks syntactically just like doing the same for arrays and slices except that the index doesn't need to be an integer.

在语法上，map 的赋值、取值操作与 array 和 slice 的用法类似，仅有一点不同，即 map 的索引不必为数值型。

offset := timeZone["EST"]

An attempt to fetch a map value with a key that is not present in the map will return the zero value for the type of the entries in the map. For instance, if the map contains integers, looking up a non-existent key will return 0. A set can be implemented as a map with value type bool. Set the map entry to true to put the value in the set, and then test it by simple indexing.

获取一个 map 中不存在的 key 将返回 map 对应值类型的零值。例如，假设 map 中存储整型值，获取一个不存在的 key 会返回 0。可以用包含 bool 类型的 map 实现一个集合，通过向该集合中添加值来设置该条目为 true，这样就可以通过简单的索引取值来测试真假。

attended := map[string]bool{
    "Ann": true,
    "Joe": true,
    ...
}

if attended[person] { // will be false if person is not in the map
    fmt.Println(person, "was at the meeting")
}

Sometimes you need to distinguish a missing entry from a zero value. Is there an entry for "UTC" or is that 0 because it's not in the map at all? You can discriminate with a form of multiple assignment.

有时需要区分零值和缺失项，“UTC” 的条目不存在？还是存在但值为 0 ？你可以使用多重赋值的形式进行区分。

var seconds int
var ok bool
seconds, ok = timeZone[tz]

For obvious reasons this is called the “comma ok” idiom. In this example, if tz is present, seconds will be set appropriately and ok will be true; if not, seconds will be set to zero and ok will be false. Here's a function that puts it together with a nice error report:

显而易见，我们称这种方式为 "comma ok" 风格。在此例中，如果 tz 存在，seconds 会被设置恰当，且 ok 为 true；否则，seconds 会被置零且 ok 为 false。下面是一个联合使用范例：

func offset(tz string) int {
    if seconds, ok := timeZone[tz]; ok {
        return seconds
    }
    log.Println("unknown time zone:", tz)
    return 0
}

To test for presence in the map without worrying about the actual value, you can use the blank identifier (_) in place of the usual variable for the value.

若仅仅想测试 key 是否存在，而不关心其值的话，可以使用空白标识符（_）来忽略之。

_, present := timeZone[tz]

To delete a map entry, use the delete built-in function, whose arguments are the map and the key to be deleted. It's safe to do this even if the key is already absent from the map.

使用内建函数 delete 来删除 map 中的条目，其参数为该 map 和要删除的 key。即便 key 不存在，执行 delete 也是安全的，不会 panic。

delete(timeZone, "PDT")  // Now on Standard Time

Printing

Formatted printing in Go uses a style similar to C's printf family but is richer and more general. The functions live in the fmt package and have capitalized names: fmt.Printf, fmt.Fprintf, fmt.Sprintf and so on. The string functions (Sprintf etc.) return a string rather than filling in a provided buffer.

Go 的格式化打印类似于 C 语言的 printf 家族，但更加丰富和广泛。它们是位于 fmt 包中首字母大写的函数：fmt.Printf，fmt.Fprintf， fmt.Sprintf 等等。字符串函数（ Sprintf 之类 ）直接返回一个字符串，而不是填充一个提供的 buffer（译注：区别于 C 语言的 sprintf）。

You don't need to provide a format string. For each of Printf, Fprintf and Sprintf there is another pair of functions, for instance Print and Println. These functions do not take a format string but instead generate a default format for each argument. The Println versions also insert a blank between arguments and append a newline to the output while the Print versions add blanks only if the operand on neither side is a string. In this example each line produces the same output.

使用格式化字符串并不总是必须的。Printf，Fprintf 和 Sprintf 中每一个都有另一对函数可供使用，它们是不需要格式化字符串的，例如 Print 和 Println。这些函数不需要格式化字符串，而是为每个参数生成一个默认格式。Println 总会在参数之间插入一个空格，并且在末尾换行，之后将字符串打印到标准输出，而 Print 只有在两个参数都不是字符串时才插入空格。此例中，每一行打印的内容相同。

fmt.Printf("Hello %d\n", 23)
fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
fmt.Println("Hello", 23)
fmt.Println(fmt.Sprint("Hello ", 23))

The formatted print functions fmt.Fprint and friends take as a first argument any object that implements the io.Writer interface; the variables os.Stdout and os.Stderr are familiar instances.

fmt.Fprint 家族函数使用一个实现了 io.Writer 接口的对象作为首个参数；我们耳熟能详的 os.Stdout 和 os.Stderr 就实现了 io.Writer 接口。

Here things start to diverge from C. First, the numeric formats such as %d do not take flags for signedness or size; instead, the printing routines use the type of the argument to decide these properties.

接下来的内容就与 C 语言分道扬镳了。首先像 %d 这样的数值格式不需要符号或者大小标记；而是由打印例程根据其参数类型来决定相关属性。

var x uint64 = 1<<64 - 1
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))

prints

将打印

18446744073709551615 ffffffffffffffff; -1 -1

If you just want the default conversion, such as decimal for integers, you can use the catchall format %v (for “value”); the result is exactly what Print and Println would produce. Moreover, that format can print any value, even arrays, slices, structs, and maps. Here is a print statement for the time zone map defined in the previous section.

如果只需要默认转换（如整数的十进制），则可以使用捕获格式 %v（即 value）；其结果正是 Print 和 Println 产生的输出。而且 %v 可以打印任意值，甚至是 arrays，slices，structs，和 maps。下面的语句打印之前定义的时区 map。

fmt.Printf("%v\n", timeZone)  // or just fmt.Println(timeZone)

which gives output:

将输出：

map[CST:-21600 EST:-18000 MST:-25200 PST:-28800 UTC:0]

For maps, Printf and friends sort the output lexicographically by key.

对于 map 来说，Printf 及其家族函数使用 key 作字典排序。

When printing a struct, the modified format %+v annotates the fields of the structure with their names, and for any value the alternate format %#v prints the value in full Go syntax.

打印结构体时，改进版格式 %+v 将在字段前面冠以名称，而且对于任意值，另一种格式 %#v 将以 Go 的完整语法打印该值。

type T struct {
    a int
    b float64
    c string
}
t := &T{ 7, -2.35, "abc\tdef" }
fmt.Printf("%v\n", t)
fmt.Printf("%+v\n", t)
fmt.Printf("%#v\n", t)
fmt.Printf("%#v\n", timeZone)

prints

打印

&{7 -2.35 abc   def}
&{a:7 b:-2.35 c:abc     def}
&main.T{a:7, b:-2.35, c:"abc\tdef"}
map[string]int{"CST":-21600, "EST":-18000, "MST":-25200, "PST":-28800, "UTC":0}

(Note the ampersands.) That quoted string format is also available through %q when applied to a value of type string or []byte. The alternate format %#q will use backquotes instead if possible. (The %q format also applies to integers and runes, producing a single-quoted rune constant.) Also, %x works on strings, byte arrays and byte slices as well as on integers, generating a long hexadecimal string, and with a space in the format (% x) it puts spaces between the bytes.

（注意 & 符号）通过 %q 也能实现字符串添加双引号的格式，另一种 %#q 会尝试使用反引号。（%q 也能作用于数值或者 rune，产生一个带单引号的 rune 常量），此外，%x 可作用于字符串、字节数组和字节切片以及整数，生成一个长的十六进制字符串，并且在格式中增加空格的话（% x），会在字节之间放置空格。

Another handy format is %T, which prints the type of a value.

另一常用的格式是 %T，它将打印值的类型。

fmt.Printf("%T\n", timeZone)

prints

打印

map[string]int

If you want to control the default format for a custom type, all that's required is to define a method with the signature String() string on the type. For our simple type T, that might look like this.

若想定制自定义类型的默认打印格式，仅需在相应类型上实现一个签名为 String() string 的方法即可。如我们定义的简单类型 T，可能实现如下：

func (t *T) String() string {
    return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
}
fmt.Printf("%v\n", t)

to print in the format

以自定义格式打印

7/-2.35/"abc\tdef"

(If you need to print values of type T as well as pointers to T, the receiver for String must be of value type; this example used a pointer because that's more efficient and idiomatic for struct types. See the section below on pointers vs. value receivers for more information.)

（如果你需要打印 T 的值，就像打印 T 的指针那样，那么 String 方法的接收者就必须是一个值；此例使用指针，是因为对结构体类型来说这种用法即高效又地道。详见 pointers vs. value receivers 章节）

译注：关于值和指针接收者的方法集合（method sets），有两条准则：

1. 对 T 的值来说，只有接收者为值类型的方法才属于值类型的方法集合
2. 对 T 的的指针来说，该类型上实现的所有方法，不管接收者是值类型还是指针类型都属于指针的方法集合

虽然编译器的语法糖让我们在调用方法时不用操心是值还是指针，但在和接口一起工作时，编译器不会作此调整。

Our String method is able to call Sprintf because the print routines are fully reentrant and can be wrapped this way. There is one important detail to understand about this approach, however: don't construct a String method by calling Sprintf in a way that will recur into your String method indefinitely. This can happen if the Sprintf call attempts to print the receiver directly as a string, which in turn will invoke the method again. It's a common and easy mistake to make, as this example shows.

我们的 String 方法之所以能够调用 Sprintf ，完全是因为 print 例程是可重入的，并且可以以这种方式封装。需要铭记的一点：无论如何，都不要使用 Sprintf 构造调用自定义 String 的方法，这将造成死循环。这常发生在 Sprintf 尝试打印接收者自身时，这会导致无限循环调用。这是个很容易犯错的地方，就像下例：

type MyString string

func (m MyString) String() string {
    return fmt.Sprintf("MyString=%s", m) // Error: will recur forever.
}

It's also easy to fix: convert the argument to the basic string type, which does not have the method.

修复起来很简单，只要将参数转换为不具备此接口的基础类型即可：

type MyString string
func (m MyString) String() string {
    return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion.
}

In the initialization section we'll see another technique that avoids this recursion.

在初始化章节中，我们将看到使用另一种技巧来避免这种递归调用。

Another printing technique is to pass a print routine's arguments directly to another such routine. The signature of Printf uses the type ...interface{} for its final argument to specify that an arbitrary number of parameters (of arbitrary type) can appear after the format.

另一种打印技巧是将打印例程的参数直接传递给另一个类似的例程。Printf 的签名使用类型 ...interface{} 作为其最后的参数，这明确指出任意数量、任意类型的参数可以跟在 format 之后。