根本原因是.api文件缺失或路径/内容不合法，导致goctl生成的handler、logic、types全为空包，svc.servicecontext中依赖（如usermodel）为nil，后续调用直接崩溃；.api文件须放api/目录下、编码utf-8无bom、含type声明，且main.go中需正确初始化并传入&servicecontext。
goctl 生成的 handler 一启动就 panic nil pointer 怎么办
根本原因是 .api 文件缺失或路径/内容不合法，导致 goctl 生成的 handler、logic、types 全为空包，svc.ServiceContext 中依赖（如 userModel）为 nil，后续调用直接崩溃。
-
.api文件必须放在api/目录下，例如api/user.api；执行命令时路径要完全匹配：goctl api go -api api/user.api -dir . -
user.api至少要包含type声明（定义请求/响应结构体），否则types包为空，所有引用该结构体的地方都会 panic - 文件编码必须是 UTF-8 无 BOM —— Windows 记事本默认带 BOM，推荐用 VS Code 或 Goland 编辑并手动设编码
- 检查
internal/handler中 handler 初始化是否传入了非空svc.ServiceContext；该 context 必须在main.go中通过conf.MustLoad构造并传入，不能漏掉取地址符&c
etc/user.yaml 配置项始终不生效
go-zero 不扫描、不热加载配置，conf.Load 是唯一入口，且字段 tag 与 YAML 键名必须严格一致 —— 差一个字母、多一个空格，整个字段就是零值。
- YAML 中的 key 必须全小写，与 struct tag 完全对应：比如
Port int `json:"port"`对应port: 8080，写成Port或PORT都无效 - 嵌套结构体用点号分隔：如
Database.Host对应 YAML 中database:下一级的host: - 如果用了 Etcd 配置中心，确保
registry字段类型是etcd，且Etcd结构体的 tag 写对了（例如etcd:"host"），否则 client 初始化失败
RPC 第一次调用特别慢，之后又正常
这不是网络抖动或服务端响应慢，而是 go-zero 的 rpcxclient 默认懒加载连接池 —— 首次调用才触发 DNS 解析、TCP 握手、TLS 协商，耗时几百毫秒甚至更久。
- 解决办法不是加超时，而是预热：在服务启动后、对外提供流量前，主动调用一次目标 RPC 方法（哪怕只传空参）
- 避免在 handler 或 logic 的 hot path 上做首次调用；可放在
main.go的init()或start()后立即执行 - 若使用了负载均衡，预热需覆盖全部实例；单实例部署可直接调用
client.Ping()类方法触发建连
WebSocket 广播卡在 500 连接就延迟飙升
瓶颈不在网络带宽，而在全局锁 + 阻塞写 —— 用 map[*websocket.Conn] + sync.RWMutex 遍历写，每个 conn.WriteMessage 都串行化，且任一客户端网络差就会拖垮全部。
- 改用「连接分组 + 无锁 chan」：每个连接绑定独立
chan []byte，由专属 goroutine 从 chan 读消息并写 socket - 广播时只往各连接的 chan 发送，完全避开锁和遍历操作
- 务必给
conn.SetWriteDeadline和conn.SetReadDeadline设值（如 30 秒），否则中间代理（Nginx/Cloudflare）会静默断连 - 服务端要手动处理 Ping/Pong：
conn.SetPingHandler回写websocket.PongMessage，否则连接几秒后报close 1006
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
