goctl生成代码更可靠，因其将rpc接口定义、http路由绑定、dto结构体、dao调用链及错误码统一耦合进api/rpc dsl，避免手写遗漏context透传或error wrap导致日志断裂或panic泄露。
为什么直接用 goctl 生成代码比手写 service 更可靠
因为 goctl 不只是模板填充工具，它把 RPC 接口定义、HTTP 路由绑定、DTO 结构体、DAO 层调用链、错误码统一管理全部耦合进一套 DSL（api 和 rpc 文件），手写极易漏掉中间某层的 context 透传或 error wrap，导致日志链路断裂或 panic 泄露。
实操建议：
- 所有业务接口必须先写
user.api文件，再执行goctl api go -api user.api -dir .；不要反向“从 handler 补 api 定义” -
goctl rpc proto生成的pb包名必须和.proto文件里package声明一致，否则go build会报undefined: xxxService - HTTP 层若需校验 token，别在
handler里硬写 jwt.Parse，应通过middleware注册，且 middleware 必须在svc.Use()中显式启用
RPC 服务启动失败时，etcd 连接超时不是唯一原因
常见现象是 panic: context deadline exceeded 报在 registry.NewEtcdRegistry，但实际可能卡在 DNS 解析、etcd TLS 证书不匹配、或本地 /etc/hosts 里配置了错误的 etcd 域名映射。
排查步骤：
- 先用
telnet your-etcd-host 2379确认端口可达；若不通，检查防火墙或 k8s Service 是否暴露正确端口 - 如果启用了 TLS，确认
etcd配置中tls字段指向的 cert/key 文件路径可读，且 ca 证书与 etcd server 端签发者一致 - Go-Zero 默认使用
etcdv3，但某些私有环境仍跑着 etcd v2——必须降级用github.com/micro/go-plugins/registry/etcd，否则注册永远失败
go-zero 的 sqlx 自动扫描对 NULL 值处理很脆弱
比如数据库字段定义为 status TINYINT NULL，而 struct 字段写成 Status int `db:"status"`，查询时只要该行 status 为 NULL，sqlx.StructScan 就直接 panic："cannot scan NULL into Go struct field"。
安全写法：
- 所有可能为 NULL 的字段，对应 struct 字段必须用指针类型，例如
*int、*string、*time.Time - 如果业务逻辑需要默认值（如 NULL 当作 0），不要在 DAO 层做
if v == nil { v = new(int); *v = 0 }，应在 service 层统一转换，保持 DAO 纯粹性 - 用
sqlx.In构造批量插入时，注意[]interface{}中不能混入nil指针，否则sqlx会 panic；应提前过滤或用sql.NullInt64类型替代
本地调试时，go run 启动多个服务总连不上彼此
根本原因是 Go-Zero 默认使用 zookeeper 或 etcd 做服务发现，而本地没起注册中心，client 初始化时会无限重试连接，最终超时返回 rpc error: code = Unavailable。
快速绕过方案：
- 开发阶段改用直连模式：在 client 初始化处，把
registry替换为rpcx.NewDirectClient，传入目标服务的127.0.0.1:8081 - 或者启动一个轻量 etcd：
docker run -d -p 2379:2379 --name etcd-server -e ETCD_ADVERTISE_CLIENT_URLS=http://0.0.0.0:2379 quay.io/coreos/etcd:v3.5.10，再确保各服务配置里的etcd.Hosts是["http://127.0.0.1:2379"] - 切记：
go run不能跨 terminal 共享进程，每个服务必须单独开终端运行；用make dev脚本统一管理时，要加sleep确保 etcd 先就绪
最易被忽略的是配置热加载边界：Go-Zero 的 conf.Load 只监听文件变更，但不会自动 reload RPC client 的 endpoint 列表——服务重启前务必手动触发一次 registry 重新订阅，否则新上线实例永远不被发现。
