创建仓库

2025-12-11 07:24:36 +08:00
commit 0d81c1792d
128 changed files with 15104 additions and 0 deletions
--- a/Go项目实战/00_顶层设计/00_软件产品全生命周期管理规范.md
+++ b/Go项目实战/00_顶层设计/00_软件产品全生命周期管理规范.md
@@ -0,0 +1,159 @@
+---
+tags: []
+aliases:
+  - 📘 软件产品全生命周期管理规范 (PDLC Guidelines)
+date created: 星期日, 十二月 7日 2025, 12:49:19 下午
+date modified: 星期日, 十二月 7日 2025, 12:49:54 下午
+---
+这是一个通用的、标准化的《互联网软件产品全生命周期（PDLC）管理规范》。此文档旨在为从灵感到交付的全过程提供顶层指导，适用于中大型项目或追求工程卓越的小型团队。
+
+---
+
+# 📘 软件产品全生命周期管理规范 (PDLC Guidelines)
+
+版本: 2.0 (通用标准版)
+
+适用范围: 全栈开发、SaaS 产品、企业级应用系统
+
+核心目标: 降低不确定性，确保交付质量，实现可预测的工程化产出。Shutterstock
+
+---
+
+## 阶段概览 (Phase Overview)
+
+我们将产品落地过程划分为 7 个核心阶段（P0 - P6）。每个阶段都有明确的准入（Entry）和准出（Exit）标准。
+
+|**阶段代号**|**阶段名称**|**核心角色**|**关键产出物**|
+|---|---|---|---|
+|**P0**|**立项与价值验证 (Inception)**|PM, Tech Lead, Stakeholder|BRD, 可行性分析报告|
+|**P1**|**需求定义与原型 (Definition)**|PM, UI/UX|PRD, 原型图 (Figma)|
+|**P2**|**技术方案设计 (Technical Design)**|Architect, Backend, Frontend|TDD, API 契约, ER 图|
+|**P3**|**开发与实现 (Development)**|Developers|源代码, 单元测试|
+|**P4**|**质量保障与验证 (Verification)**|QA, Developers|测试报告, Bug 清单|
+|**P5**|**发布与部署 (Release)**|DevOps, Tech Lead|镜像, Release Note|
+|**P6**|**运维与迭代 (Operations)**|SRE, Ops, PM|监控面板, 运营数据报告|
+
+---
+
+## 📅 详细阶段拆解
+
+### P0: 立项与价值验证 (Inception & Strategy)
+
+**目的:** 明确“为什么要做”。防止团队在伪需求或技术不可行的方向上浪费资源。
+
+- **主要工作:**
+    
+    1. **商业需求分析:** 确定业务痛点、目标用户及商业价值。
+    2. **技术可行性预研 (PoC):** 针对关键技术难点（如 AI 模型效果、高并发瓶颈）进行快速验证。
+    3. **资源评估:** 粗略估算所需人力、时间及服务器成本。
+        
+- **关键产出 (Artifacts):**
+    - `BRD (Business Requirement Document)`：商业需求文档。
+    - `PoC Demo`：概念验证原型（如有必要）。
+- **决策门 (Gate):** **Go / No-Go**。如果 ROI（投入产出比）过低，在此阶段终止。
+
+### P1: 需求定义与产品设计 (Product Definition)
+
+**目的:** 明确“要做成什么样”。将模糊的想法转化为具象的功能逻辑和视觉形态。
+
+- **主要工作:**
+    
+    1. **需求细化:** 编写详细的功能列表、用户故事 (User Stories) 和验收标准 (AC)。
+    2. **交互设计 (UX):** 绘制用户流程图 (User Flow)、低保真线框图。
+    3. **视觉设计 (UI):** 输出高保真设计稿、UI 切图、设计规范 (Design System)。
+        
+- **关键产出 (Artifacts):**
+    - `PRD (Product Requirement Document)`：产品需求规格说明书（唯一真理来源）。
+    - `Figma/Sketch Files`：高保真设计稿。
+- **决策门 (Gate):** **需求评审 (PRD Review)**。开发团队确认需求逻辑闭环，无歧义。
+
+### P2: 技术方案设计 (Technical Design)
+
+**目的:** 明确“怎么实现”。**这是程序员最重要的规划阶段，严禁跳过此阶段直接编码。**
+
+- **主要工作:**
+    
+    1. **架构设计:** 确定微服务拆分、技术选型、中间件依赖（Redis/MQ/DB）。
+    2. **数据建模 (Schema Design):** 绘制 ER 图，编写 DDL (SQL 建表语句)，确定索引策略。
+    3. **接口定义 (API Contract):** 定义 URL、Method、Request/Response JSON 结构、错误码。
+    4. **详细设计 (TDD):** 核心算法逻辑、状态机流转图、时序图、缓存策略设计。
+        
+- **关键产出 (Artifacts):**
+    - `TDD (Technical Design Document)`：技术设计文档。
+    - `ER Diagram & SQL Scripts`：数据库模型与迁移脚本。
+    - `OpenAPI/Swagger Spec`：API 接口定义文档。
+- **决策门 (Gate):** **技术评审 (Design Review)**。架构师或 Tech Lead 确认方案具备扩展性、安全性及性能达标。
+
+### P3: 开发与实现 (Implementation)
+
+**目的:** 将设计转化为代码。注重代码质量与规范。
+
+- **主要工作:**
+    
+    1. **环境准备:** 本地开发环境搭建、Mock 数据生成。
+    2. **编码 (Coding):** 后端 API 开发、前端组件开发、业务逻辑实现。
+    3. **单元测试 (Unit Test):** 编写核心逻辑的单元测试，确保覆盖率。
+    4. **代码审查 (Code Review):** 提交 Merge Request，进行同行评审。
+        
+- **关键产出 (Artifacts):**
+    - `Source Code`：符合规范的源码。
+    - `Unit Test Report`：单元测试通过报告。
+- **决策门 (Gate):** **代码合并 (Merge)**。CI 流水线检查通过（Lint, Test, Build）。
+
+### P4: 质量保障与验证 (Quality Assurance)
+
+**目的:** 确保交付物符合需求且无重大缺陷。
+
+- **主要工作:**
+    
+    1. **集成测试:** 前后端联调，确保接口数据交互正常。
+    2. **系统测试:** QA 团队根据测试用例进行全量测试。
+    3. **非功能测试:** 性能测试 (Load Test)、安全扫描 (Security Scan)。
+    4. **Bug 修复:** 开发修复 QA 发现的问题并回归。
+        
+- **关键产出 (Artifacts):**
+    - `Test Cases`：测试用例。
+    - `Bug List`：缺陷清单及修复记录。
+    - `Performance Report`：压测报告（可选）。
+- **决策门 (Gate):** **验收评审 (UAT)**。Bug 清零或无 P0/P1 级 Bug，PM 验收通过。
+
+### P5: 发布与部署 (Release & Deployment)
+
+**目的:** 安全、平滑地将产品推向生产环境。
+
+- **主要工作:**
+    
+    1. **构建交付:** 编译二进制文件、构建 Docker 镜像。
+    2. **预发布验证 (Staging):** 在仿真环境中进行最后一次冒烟测试。
+    3. **正式部署 (Production):** 灰度发布 (Canary) 或 蓝绿部署，执行数据库迁移。
+    4. **回滚预案:** 准备好一旦失败的一键回滚脚本。
+        
+- **关键产出 (Artifacts):**
+    - `Release Note`：发布说明（变更日志）。
+    - `Docker Image / Binaries`：制品。
+- **决策门 (Gate):** **上线检查清单 (Checklist)**。确认配置、密钥、数据库备份均已就绪。
+
+### P6: 运维与持续迭代 (Operations & Maintenance)
+
+**目的:** 保障系统稳定性，根据反馈进行优化。
+
+- **主要工作:**
+    
+    1. **监控告警:** 配置 CPU/内存、QPS、错误率监控，设置 PagerDuty 告警。
+    2. **日志审计:** 收集与分析运行日志 (ELK/Loki)。
+    3. **数据复盘:** 分析用户行为数据，验证 P0 阶段的商业假设。
+    4. **事故复盘 (Post-mortem):** 若发生故障，撰写复盘报告，制定改进措施。
+        
+- **关键产出 (Artifacts):**
+    - `SLA Report`：服务可用性报告。
+    - `User Analytics`：用户数据分析报表。
+
+---
+
+## ⚙️ 关键支撑体系 (Supporting Pillars)
+
+除了上述流程，以下三个支撑体系贯穿始终：
+
+1. **项目管理 (Project Management):** 使用 Jira/Trello 管理任务看板，每日站会同步进度，识别风险。
+2. **配置管理 (Configuration Management):** 代码版本控制 (Git Flow)，环境配置隔离 (Env Vars)。
+3. **文档工程 (Documentation):** 保持 BRD, PRD, API 文档与代码的同步更新，避免“文档腐烂”。
--- a/Go项目实战/00_顶层设计/一个Go项目的基本骨架.md
+++ b/Go项目实战/00_顶层设计/一个Go项目的基本骨架.md
@@ -0,0 +1,34 @@
+---
+tags: []
+date created: 星期日, 十二月 7日 2025, 11:44:41 中午
+date modified: 星期日, 十二月 7日 2025, 11:57:43 中午
+---
+
+```plaintext
+your-api-project/
+├── cmd/
+│   └── server/
+│       ├── main.go           # 调用 wire 注入，获取 app 实例，执行 app.Run()
+│       └── wire.go           # Wire 依赖注入
+├── config/                   # Viper 配置结构体
+├── internal/
+│   ├── api/                  # (DTO层) 纯数据传输对象，无逻辑
+│   │   ├── request/
+│   │   └── response/
+│   ├── controller/           # (接口层) 解析 request -> 调 service -> 组装 response
+│   ├── service/              # (应用服务层) 编排业务逻辑，操作 Entity
+│   ├── repository/           # (资源层) 负责 CRUD，屏蔽数据库差异
+│   ├── entity/               # (领域层) 核心业务实体 (User, Article)，带 GORM tag
+│   ├── router/               # (路由层) NewRouter() *gin.Engine
+│   └── middleware/           # Gin 中间件
+├── pkg/                      # (基础设施层) 通用工具
+│   ├── app/                  # 统一响应封装 (Gin Result)
+│   ├── auth/                 # JWT 签发与解析
+│   ├── hasher/               # 密码加密 (Argon2 / Bcrypt)
+│   ├── logger/               # Zap 配置
+│   └── timeutil/             # 时间处理工具
+├── migrations/               # 数据库变更 SQL
+├── docs/                     # Swagger
+├── go.mod
+└── Makefile
+```
--- a/Go项目实战/00_顶层设计/关于个人开发者的开发模式.md
+++ b/Go项目实战/00_顶层设计/关于个人开发者的开发模式.md
@@ -0,0 +1,109 @@
+---
+tags: []
+aliases:
+  - 渐进式开发最佳实践
+date created: 星期一, 十二月 8日 2025, 12:04:31 凌晨
+date modified: 星期一, 十二月 8日 2025, 12:05:12 凌晨
+---
+
+# 渐进式开发最佳实践
+
+## 1. 必须在写代码前锁定的“硬约束” (The Non-Negotiables)
+
+即使是后规划细节，但这 **4 样东西** 是一旦开工就很难改的，必须在骨架阶段定死：
+
+1. **目录结构 (Directory Layout):** `cmd`, `internal`, `pkg` 怎么分。这决定了你能不能顺畅地加代码。
+    
+    - _现状:_ 我们已经定好了 (Modular Clean Architecture)。
+        
+2. **核心技术栈与基础设施:** 选 Gin 还是 Echo，用 GORM 还是 SQLX，依赖注入用 Wire 还是手写。
+    
+    - _现状:_ 我们已经定好了 (Gin+GORM+Wire+Viper)。
+        
+3. **统一的交互规范:** API 怎么返回错误？数据库怎么管理变更？日志打在哪里？
+    
+    - _现状:_ 我们已经定好了 (JSON Envelope, Golang-Migrate, Zap)。
+        
+4. **核心领域模型 (Core Schema):** 最关键的表（User, Role）。
+    
+    - _原因:_ 它们是系统的地基，地基不稳，后面写 Service 逻辑会反复推倒重来。
+
+---
+
+## 2. 可以（且应该）推迟设计的“软逻辑” (The Deferrables)
+
+这些内容不要现在想，想了也是白想，等写到那个函数时再具体的“具体问题具体分析”：
+
+1. **复杂的业务算法:** 比如“文章的热度排名算法”、“复杂的权限递归校验逻辑”。
+    
+    - _策略:_ 先写个 `return true` 或简单的逻辑占位，跑通流程再说。
+        
+2. **极致的性能优化:** 比如“这里要不要加 Redis 缓存？”、“这里 SQL 要不要分表？”。
+    
+    - _策略:_ 先跑通功能 (Make it work)，再优化性能 (Make it fast)。
+        
+3. **非核心字段的定义:** 比如文章表里要不要加 `seo_keywords`，用户表要不要加 `wechat_id`。
+    
+    - _策略:_ 用到了再加 migration，不要为了“未来可能用到”而过度设计。
+        
+4. **具体的 API 参数细节:** 比如“更新文章是传 ID 还是传 UUID”。
+    
+    - _策略:_ 写 Handler 的时候，顺手定义 DTO 就行。
+
+---
+
+## 3. 个人开发者的“曳光弹”开发流 (The Tracer Bullet Workflow)
+
+不要试图“横向”开发（先把所有 50 张表设计完，再把所有 API 定义完）。
+
+要进行 “纵向”切片开发（Vertical Slice）。
+
+**推荐的实操步骤：**
+
+### 第一阶段：搭建“行走的骨架” (Day 1 - 也就是你现在该做的)
+
+**目标：** 一个能跑起来、能连数据库、有日志、有 Swagger 文档，但没有任何业务功能的空壳。
+
+1. **初始化项目:** 建立文件夹，`go mod init`。
+2. **配置基础设施:** 放入 `Makefile`, `docker-compose.yml`, `config.yaml`。
+3. **连通性测试:** 写一个简单的 `GET /ping` 接口，确保能读到配置，能连上 DB，能打出日志。
+4. **依赖注入跑通:** 确保 `wire` 能自动生成代码并启动 Server。
+5. **结果:** 你拥有了一个**“生产级”的 Hello World**。
+
+### 第二阶段：第一个“核心切片” (Day 2-3)
+
+**目标:** 打通 User 模块的完整闭环。
+
+1. **DB:** 设计 `users` 表，执行 Migrate。
+2. **Entity:** 生成 User Struct。
+3. **Repo:** 写 `CreateUser` 和 `FindUser` 的 CRUD。
+4. **Service:** 写 `Register` 逻辑（这里涉及到密码加密，此时再去查 Argon2 怎么用）。
+5. **API:** 定义 `RegisterReq` DTO，写 Handler。
+6. **测试:** 用 Postman/Swagger 调通注册接口。
+
+### 第三阶段：具体问题具体分析 (Day 4+)
+
+**目标:** 遇到什么写什么。
+
+- _场景:_ 比如你做到了“文章发布”，突然发现需要“敏感词过滤”。
+- _动作:_ 停下来，在 `pkg/util` 里设计一个敏感词过滤函数（或者找个库），然后在 Service 层调用它。
+- _这就是你说的:_ “进行到具体的业务逻辑的时候进行设计”。
+
+---
+
+## 4. 总结给你的建议
+
+你现在的焦虑在于试图**预见未来**。
+
+**作为个人开发者，你的代码就是你的设计文档。**
+
+**你的下一步行动：**
+
+1. **停止**思考复杂的业务场景。
+2. **立即**按照我们之前确定的目录结构，新建文件夹。
+3. **立即**把 `docker-compose` 跑起来，把 `main.go` 跑起来。
+4. **立即**实现“用户注册”这一个功能。
+
+只要“骨架”（架构分层、依赖注入、数据库管理方式）是对的，后面你往里面填什么肉（业务逻辑），怎么填，都不会把楼盖歪。
+
+**准备好开始初始化项目文件夹了吗？**
--- a/Go项目实战/00_顶层设计/关于项目的顶层设计模式和风格.md
+++ b/Go项目实战/00_顶层设计/关于项目的顶层设计模式和风格.md
@@ -0,0 +1,130 @@
+---
+tags: []
+aliases:
+  - 🏗️ Project Architecture & Design Guidelines (v1.0)
+date created: 星期日, 十二月 7日 2025, 11:57:43 中午
+date modified: 星期二, 十二月 9日 2025, 11:00:14 晚上
+---
+
+# 🏗️ Project Architecture & Design Guidelines (v1.0)
+
+项目代号: Enterprise-CMS-Core
+
+架构风格: 模块化整洁架构 (Modular Clean Architecture)
+
+核心原则: 实用主义 (Pragmatic)、Go 原生思维 (Idiomatic)、领域驱动 (DDD-Lite)
+
+## 1. 技术栈约束 (Tech Stack Constraints)
+
+- **Language:** Go 1.21+
+- **Web Framework:** Gin
+- **Database:** PostgreSQL (Primary), Redis (Cache)
+- **ORM:** GORM (With Migration Tools)
+- **Dependency Injection:** Google Wire
+- **Configuration:** Viper (YAML)
+- **Observability:** Zap (Log), Prometheus (Metrics), Jaeger (Trace)
+- **Documentation:** Swagger / OpenAPI 3.0
+
+---
+
+## 2. 目录结构规范 (Directory Structure)
+
+采用 **“按领域分包 (Package by Domain)”** 的扁平化结构，而非传统的按层分包。
+
+```Plaintext
+root/
+├── cmd/server/
+│   ├── main.go             # 仅包含 wire 初始化与 app.Run()
+│   └── wire.go             # 顶层依赖注入定义
+├── config/                 # 配置文件模板 (config.yaml)
+├── internal/
+│   ├── api/                # [API层] 全局通用的 HTTP DTO (Request/Response)
+│   ├── middleware/         # [中间件] Gin 中间件 (Auth, CORS, Logger)
+│   ├── pkg/                # [基础设施] 内部通用组件 (AppResult, ErrorCode)
+│   │
+│   │   # --- 核心业务领域 (Domain Modules) ---
+│   │   # 每个领域包内部扁平化，自包含所有逻辑
+│   ├── user/               # [示例] 用户领域
+│   │   ├── entity.go       # 核心实体 (GORM Model)
+│   │   ├── repository.go   # 仓储接口定义 + GORM 实现
+│   │   ├── service.go      # 业务逻辑 (Service Struct)
+│   │   ├── handler.go      # HTTP 控制器 (Controller)
+│   │   └── provider.go     # Wire ProviderSet
+│   │
+│   └── article/            # [示例] 文章领域 (结构同上)
+│
+├── pkg/                    # [外部库] 可抽离的通用工具 (Hash, JWT, Logger封装)
+├── migrations/             # 数据库迁移 SQL 文件 (up/down)
+├── go.mod
+└── Makefile
+```
+
+---
+
+## 3. 核心架构设计规则 (Architectural Rules)
+
+### 3.1. 依赖倒置与注入 (IoC & DI)
+
+- **规则:** 严禁在业务代码中手动 `New()` 依赖对象。
+- **实现:** 所有依赖关系必须通过 `NewStruct(dep Interface)` 构造函数声明，并由 `Google Wire` 在编译期自动组装。
+- **模块化注入:** 每个领域包（如 `internal/user`）必须包含一个 `provider.go`，导出 `var ProviderSet = wire.NewSet(…)`，供顶层 `cmd/server/wire.go` 聚合。
+
+### 3.2. 接口策略 (Interface Strategy)
+
+- **Repository (必须):** 仓储层**必须**定义接口（例如 `UserRepository`），以支持 Mock 测试和数据库切换。
+- **Service (按需):** 默认**不需要**定义 Service 接口，直接使用 Struct。仅在以下情况提取接口：
+    
+    1. 出现循环依赖。
+    2. 需要对 Service 进行 Mock 测试。
+    3. 该 Service 存在多种策略实现（如 `PaymentService` 有支付宝/微信两种实现）。
+
+### 3.3. 领域包扁平化 (Flat Domain Package)
+
+- **规则:** 在 `internal/user/` 等领域包内，**不再**建立 `service/`, `repo/` 子目录。
+- **原因:** 利用 Go 的 `package` 级私有可见性，隐藏领域内部细节（如辅助函数、内部 DTO），仅暴露必要的 Handler 和 Service 方法。
+
+### 3.4. 数据模型 (Model Vs Entity)
+
+- **策略:** 采用 **"Pragmatic Entity"** 模式。
+- **定义:** `entity.go` 中的结构体既是业务实体，也是 GORM 模型（带 `gorm:"…"` 标签）。
+- **例外:** 只有当数据库存储结构与业务逻辑结构差异巨大时，才在 Repository 内部引入独立的 PO (Persistent Object) 并进行转换。
+
+---
+
+## 4. 编码实施标准 (Implementation Standards)
+
+### 4.1. 错误处理 (Error Handling)
+
+- **禁止:** 严禁直接返回 `error` 字符串给前端。
+- **必须:** Service 层返回标准 `error`，Controller 层通过 `pkg/app` 将其转换为统一响应格式。
+- **格式:**
+
+    ```Go
+    // Response JSON
+    {
+        "code": 20001,
+        "msg": "User already exists",
+        "data": null
+    }
+    ```
+
+### 4.2. 数据库交互 (Database Interaction)
+
+- **禁止:** Controller 层严禁导入 `gorm` 包，严禁执行 SQL。
+- **迁移:** 生产环境严禁使用 `AutoMigrate`。必须使用 `migrations/` 目录下的版本化 SQL 脚本进行变更。
+
+### 4.3. 路由注册 (Router Registration)
+
+- **规则:** 路由不再集中管理。
+- **实现:** 每个领域包暴露一个 `RegisterRoutes(r *gin.RouterGroup)` 方法。在 `main.go` 启动时，统一调用各模块的注册方法。
+
+---
+
+## 5. AI 编程指令 (Instruction for AI Agent)
+
+> **当作为 AI 助手编写代码时，请严格遵守以下指令：**
+
+1. **Context Check:** 在生成代码前，检查当前目录结构是否符合 `Section 2`。如果不符，请优先建议重构或遵循现有结构。
+2. **No Logic Leak:** 确保 HTTP 处理逻辑（解析参数、校验参数）留在 `handler.go`，业务规则（判断权限、计算）留在 `service.go`，SQL 操作留在 `repository.go`。
+3. **Wire Awareness:** 每当新增 Service 或 Repository，必须自动更新同目录下的 `provider.go`，并在 `cmd/server/wire.go` 中检查是否需要重新生成。
+4. **Testability:** 编写 Repository 代码时，优先考虑“如何 Mock”。
--- a/Go项目实战/00_顶层设计/架构设计.md
+++ b/Go项目实战/00_顶层设计/架构设计.md
@@ -0,0 +1,8 @@
+---
+tags: []
+date created: 星期日, 十二月 7日 2025, 1:14:57 下午
+date modified: 星期日, 十二月 7日 2025, 1:22:34 下午
+---
+- **部署架构:** 采用 **Modular Monolith (模块化单体)**。严禁跨模块直连数据库表。
+- **异步通信:** 引入 **Asynq (Redis)** 处理非核心路径业务（邮件、日志），拒绝 Kafka。
+- **缓存一致性:** 强制执行 **Cache-Aside + Delete on Write** 策略。