示例目录

server/examples/ 下 58 个最小可运行示例,一个框架模块一个。 别人拿到 pkg/cachex 要自己读 200 行源码、拼出正确的初始化顺序、猜哪些参数 不配会静默降级 —— 示例是开源框架降低上手成本最有效的一件工具。

怎么跑

cd server
go run ./examples/cachex

示例之间互不依赖,可以单独跑。需要外部基础设施的(Redis / DB / OSS)在示例里 用内存实现或 miniredis 顶替,不真连 —— 没配也能跑通,不会 panic。

一次跑全部:

cd server
for d in examples/*/; do n=$(basename "$d"); go run "./examples/$n" >/dev/null || echo "FAIL: $n"; done

目录约定

examples/
├── README.md              # 索引表(58 个包 → 这个示例演示什么)
├── doc.go                 # 目录级说明
├── examples_test.go       # 漂移网(4 条测试)
└── <包名>/main.go         # 一包一个目录,package main + func main()

每个示例的文件头注释就是它的说明书 —— 写清了这个包解决什么问题、关键点是什么、 跑法是什么。本手册各章的「功能」小节大多直接取材于它。

漂移网:有测试守着

server/examples/examples_test.go 里的 4 条测试:

# 约束 违反的后果
1 internal/pkg/ 下每个一级包目录都要有同名示例目录 新增框架模块忘写示例 ⇒ 测试红
2 反向:不许有多余的示例目录 删了一个包却忘了删示例 ⇒ 测试红
3 每个示例必须是 package main + func main()(go/parser 校验) 写成了伪代码 ⇒ 测试红
4 示例不许 import 业务包(internal/service / internal/model / internal/api / cmd) 别人 clone 下来编不过 ⇒ 测试红

⚠️ internal/config 不在禁用名单里 —— 它是框架的配置层,框架自己的公开 API 就会用到它。

第 4 条不是洁癖:框架示例如果 import 了业务模型,别人拿这个框架做自己的项目时, 第一个示例就编译不过 —— 而第一个示例编译不过,整套文档就废了。

两条容易被违反的纪律

① 示例必须是能跑的代码,不是伪代码

// ❌ 伪代码:能编过,但跑起来啥也不干
func purgeOldRecords(ctx context.Context) error {
    return nil // TODO: 真的去删
}

// ✅ 真的跑一遍,输出看得见

本仓的判定标准很简单:逐个 go run 冒烟全过。写示例时挖出来的真 bug (smsaudit 的 Shutdown() 不幂等、ctx key 自成一套)就是这么发现的。

② 审计三兄弟手写 DDL

piiaudit / cryptaudit / smsaudit 的表在生产上由 AutoMigrate 建,但示例 不许 import internal/model(那是业务模型包)。所以示例里**手写 CREATE TABLE

  • 裸 SQL 回查**:
const piiauditDDL = `
CREATE TABLE IF NOT EXISTS sys_pii_access_log (
    id            INTEGER PRIMARY KEY,
    created_at    DATETIME,
    ...
)`

索引

分组 包
基础设施 logger / errcode / response / validatorx / pagination / jsonid / sonyflake / timeutil / buildinfo / syncx / randomx / retryx / uainfo / metricsx / otelx / apiverx / grayx
存储与缓存 cachex / kvstore / searchidx / media / oss
安全与合规 auth / authz / casbinx / crypto / kms / desensitize / signx / idempotentx / ratelimitx / loginlock / anomalylogin / scope / fieldpolicy
审计 piiaudit / cryptaudit / smsaudit
消息与通知 inbox / notifyx / push / pushx / permnotify / msn / smslimit / smstpl / emailx
调度与可观测 cronx / jobs / slowquery
语音与媒体 voicex
业务扩展 dynx
接口文档 swaggerx

每个示例演示什么,见 examples/README.md。

results matching ""

    No results matching ""