高并发用户积分中心 (User Point System)

为什么选这个？ 它涵盖了企业级开发的核心：

API 接口设计（RESTful/gRPC）
并发处理（积分变更可能是高频操作）
数据一致性（数据库事务 + 锁）
异步处理（积分变更后异步通知下游，如发邮件/推送）

第一阶段：工程结构与核心思维

1. 标准化工程目录 (Standard Project Layout)

在企业级 Go 项目中，你不会把所有文件堆在根目录。我们需要遵循社区标准的 golang-standards/project-layout。

架构师建议的目录结构：

Plaintext

my-project/
├── cmd/                # 项目入口 (main.go 放在这)
│   └── api-server/
│       └── main.go
├── internal/           # 私有应用代码 (外部无法 import，强制模块化)
│   ├── handler/        # HTTP 处理层 (Controller)
│   ├── service/        # 业务逻辑层
│   └── model/          # 数据模型 (Structs)
├── pkg/                # 公共库 (如工具类，其他项目可引用)
│   └── util/
├── configs/            # 配置文件
├── go.mod              # 依赖管理
└── go.sum

知识点：internal 目录是 Go 编译器层面的特殊目录，它可以防止你的业务代码被其他项目随意 import，这是实现高内聚的强手段。

⚠️ 避坑指南 (Pitfall)：
循环依赖 (Circular Dependency)： Go 对循环引用非常敏感（A 引用 B，B 引用 A 会直接编译报错）。
经验： 严格分层（Layered Architecture）。Handler 层调用 Service 层，Service 层调用 Model/Repo 层，绝对不允许反向或跨层乱调。如果两层需要互相通信，请使用接口 (Interface) 解耦。

2. 接口与结构体：Go 的面向对象 (OOP in Go)

Go 没有 class，没有 extends。Go 使用组合 (Composition) 和 接口 (Interface)。

场景： 我们需要一个积分服务。

package service

// 1. 定义接口 (Contract)
// 这里的接口通常定义在"使用者"的包里，或者单独的 contract 包，但在简单架构中放在 service 层也可。
type PointService interface {
    AddPoints(ctx context.Context, userID int64, amount int) error
}

// 2. 定义结构体 (Implementation)
type pointServiceImpl struct {
    // 这里可以嵌入数据库连接池等依赖
    // db *sql.DB 
}

// 3. 构造函数 (Factory Pattern)
// 返回接口类型，而不是结构体指针，这样可以强制外部只依赖接口
func NewPointService() PointService {
    return &pointServiceImpl{}
}

// 4. 实现方法 (Receiver)
// ⚠️ 注意：这里使用 *pointServiceImpl (指针接收者)
func (s *pointServiceImpl) AddPoints(ctx context.Context, userID int64, amount int) error {
    // 业务逻辑...
    return nil
}

知识点：****鸭子类型 (Duck Typing)。只要 pointServiceImpl 实现了接口的所有方法，它就自动实现了该接口，无需 implements 关键字。

⚠️ 避坑指南 (Pitfall)：
值接收者 vs 指针接收者：
如果你要在方法里修改结构体内部的数据，必须用指针接收者 (s *struct)。
如果是大对象，为了避免拷贝性能损耗，也用指针。
经验： 企业级开发中，Service、Handler 这种有状态或单例性质的对象，统一使用指针接收者。
nil 接口不等于 nil 指针： 一个包含 nil 指针的接口变量，其本身不是 nil。这常导致 if err != nil 判断失误。

3. 并发核心：Goroutine & Channel

这是 Go 的杀手锏。在 Java 中你可能需要线程池，在 Go 中你只需要 go 关键字。

场景： 用户积分增加后，需要异步记录日志，不阻塞主流程。

func (s *pointServiceImpl) AddPoints(ctx context.Context, userID int64, amount int) error {
    // 1. 核心业务：写数据库 (同步)
    // err := db.Update(...)

    // 2. 辅助业务：异步日志 (Fire and Forget)
    // ❌ 错误做法：直接无限制地 go func()
    // go func() {
    //     uploadLog(userID)
    // }()

    // ✅ 企业级做法：使用 Channel + Worker Pool 或 信号量控制并发度
    select {
    case s.logChan <- userID: // 将任务丢入管道
        // 成功放入
    default:
        // 管道满了，降级处理（丢弃或记录本地错误），防止阻塞主流程
        fmt.Println("Log queue full, dropping log")
    }

    return nil
}

知识点： Goroutine 极其轻量（初始 2KB 栈），但它不是无限的。

⚠️ 避坑指南 (Pitfall)：
Goroutine 泄漏 (Leak)： 启动了 Goroutine 却忘了让它停止（例如卡在 channel 读写上）。这会导致内存飙升。
闭包捕获变量： 在 for 循环中使用 go func() 时，必须注意循环变量的捕获问题（注：Go 1.22 版本已修复此经典坑，但了解老版本的坑有助于理解作用域）。
Panic 导致全站崩溃： 子 Goroutine 如果发生 panic 且没有 recover，会导致整个进程（主程序）崩溃。
经验： 在每一个 go func() 的开头，务必加上 defer 来捕获 panic。

4. 上下文控制：Context

在 Go 的后端开发中，context.Context 是贯穿所有函数调用的“生命线”。

场景： 用户请求超时，后端需要取消正在进行的数据库查询。

func (s *pointServiceImpl) AddPoints(ctx context.Context, userID int64, amount int) error {
    // 模拟耗时操作
    select {
    case <-time.After(2 * time.Second):
        fmt.Println("Task finished")
    case <-ctx.Done():
        // 如果上层 HTTP 请求因为超时断开了，这里会立即收到信号
        // 我们应该立即停止工作，回滚事务
        fmt.Println("Request cancelled:", ctx.Err())
        return ctx.Err()
    }
    return nil
}

知识点： Context 用于在 Goroutine 之间传递取消信号、超时时间以及请求范围内的元数据（如 TraceID）。

⚠️ 避坑指南 (Pitfall)：
不要把 Context 放在结构体里： Context 应该是方法的第一个参数，而不是结构体的成员变量。
WithValue 的滥用： 只能用 Context 传递请求范围的元数据（如 UserID, Token），千万不要用它传递业务参数（如积分数量），否则函数签名会变得晦涩难懂，丧失类型安全。

高并发用户积分中心 (User Point System) ​

1. 标准化工程目录 (Standard Project Layout) ​

2. 接口与结构体：Go 的面向对象 (OOP in Go) ​

3. 并发核心：Goroutine & Channel ​

4. 上下文控制：Context ​

高并发用户积分中心 (User Point System)

1. 标准化工程目录 (Standard Project Layout)

2. 接口与结构体：Go 的面向对象 (OOP in Go)

3. 并发核心：Goroutine & Channel

4. 上下文控制：Context