# GoForge **Repository Path**: solidify-the-foundation/go-forge ## Basic Information - **Project Name**: GoForge - **Description**: GoForge 是一个持续演进的 Go 工程学习项目。它不收集彼此割裂的代码片段，而是将 语言特性与运行时知识沉淀为可复用模块、可运行示例、工程工具和可复现的排查记录。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-12 - **Last Updated**: 2026-08-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GoForge GoForge 是一个持续演进的 Go 工程学习项目。它不收集彼此割裂的代码片段，而是将 语言特性与运行时知识沉淀为可复用模块、可运行示例、工程工具和可复现的排查记录。 当前系统是一套带 HTTP 管理面的有界 TCP Echo 服务： ```text 客户端数据 -> 长度前缀编解码器 -> 有界 Worker Pool -> Echo 响应 -> 原子运行指标 -> HTTP 管理面 ``` 虽然系统规模不大，但已经包含一组值得深入研究的真实故障场景：畸形帧与超大帧、队列 背压、Context 取消、优雅关闭、任务 panic、goroutine 泄漏和数据竞争。 ## 项目结构 ```text cmd/goforge-server/ 可运行的 TCP 服务端 cmd/goforge-client/ 帧协议测试客户端 internal/echo/ Echo 数据面与连接生命周期 internal/admin/ 健康检查与运行指标 HTTP Handler internal/application/ 数据面和管理面的统一生命周期 pkg/codec/ 有大小限制的长度前缀帧协议 pkg/middleware/ Request ID、访问日志与 panic recovery pkg/observability/ 基于原子操作的运行指标与快照 pkg/pool/ 支持背压和优雅关闭的 Worker Pool examples/concurrency/ 并发正确用法与反面教材 docs/ 架构、模块契约与问题排查记录 ``` `pkg` 用于沉淀可复用模块，`examples` 用于隔离单个学习问题，`cmd` 与 `internal` 负责把这些模块组合成真实程序，以验证它们能否在完整调用链中协同工作。模块接缝与 设计决策参见 [架构文档](docs/architecture.md)。 ## 快速开始 环境要求：Go 1.24 或更高版本。 ```bash make check make run ``` 服务默认监听两个地址： - TCP 数据面：`127.0.0.1:7070` - HTTP 管理面：`127.0.0.1:7071` 在另一个终端中运行客户端并检查管理端点： ```bash go run ./cmd/goforge-client -message 'hello, GoForge' curl -s http://127.0.0.1:7071/healthz curl -s http://127.0.0.1:7071/metrics ``` 一次成功请求后的指标示例： ```json { "connections_accepted": 1, "connections_active": 0, "frames": 1, "payload_bytes": 14, "failures": 0 } ``` ## 工程检查 ```bash make check # 格式检查、go vet 和全部测试 make test # 单元测试与集成测试 make race # 使用 race detector 检查并发正确性 make cover # 生成核心模块覆盖率报告 make bench # 运行模块基准测试并报告内存分配 make lint # 运行 golangci-lint，需要预先安装 make vuln # 运行 govulncheck，需要预先安装 ``` 当前 Go module 路径为 `github.com/liuk/goforge`。如果项目将发布到其他账号或代码 托管平台，请在发布前执行 `go mod edit -module=<新模块路径>`，并同步更新源码中的 import 路径。 ## 学习约定 每个新知识点都必须留下可以检查和复现的成果： 1. 一份写清用途、约束和错误模式的模块接口文档，或一个聚焦问题的可运行示例； 2. 覆盖错误、取消、边界条件和资源清理的测试； 3. 涉及性能结论时提供可复现的 Benchmark； 4. 一个故意写错的反面教材，以及明确的复现和排查方法； 5. 面向生产实践的知识点必须接入现有系统，验证真实集成效果。 ## 当前学习范围 - 帧协议：字节序、短读写、内存分配边界与不可信输入； - 并发执行：channel 背压、任务取消、panic 隔离与优雅关闭； - 网络服务：连接生命周期、双平面协同关闭与 HTTP 超时策略； - 可观测性：运行指标、结构化日志、Request ID 与健康检查； - 测试策略：表驱动测试、集成测试、Benchmark、Fuzz 和 race detector； - 反面教材：goroutine 泄漏与共享计数器 data race。 ## 项目定位 GoForge 是学习和工程实践项目。帧协议、Worker Pool 与管理面刻意保持在便于阅读、 调试和测量的规模，其目标是理解标准库与工程设计，而不是替代成熟的网络框架、任务 调度库或可观测平台。