feat 初次提交

README.md

@@ -1,3 +1,171 @@
 # common
 
-公共代码集合
+公共代码集合
+
+---
+
+## ✅ 微服务十大核心原则（实战导向）
+
+> 这些不是理论教条，而是无数团队踩坑后总结出的“生存法则”。
+
+---
+
+### 1. **单一职责 & 高内聚（Single Responsibility）**
+- 每个微服务应围绕 **一个明确的业务能力**（如“用户管理”、“支付”、“通知”）。
+- ❌ 不要按技术分层拆服务（如“所有 DB 服务”、“所有 API 服务”）。
+- ✅ 建议用 **DDD（领域驱动设计）** 划分限界上下文（Bounded Context）。
+
+> 📌 口诀：**“一个服务，一个事”**
+
+---
+
+### 2. **自治性（Autonomy）**
+- 服务应能 **独立开发、测试、部署、扩展、故障恢复**。
+- 依赖越少越好；跨服务调用必须有 **降级、熔断、超时** 机制。
+- 使用 **契约测试（Contract Testing）** 保证接口兼容（如 Pact）。
+
+> 🔧 工具推荐：
+> - gRPC + Protobuf（强契约）
+> - OpenAPI（REST）
+> - WireMock / Pact（契约测试）
+
+---
+
+### 3. **数据私有（Database per Service）** ← 你已掌握！
+- 每个服务独占数据存储，**禁止跨服务直连数据库**。
+- 跨服务数据交互靠：
+    - **同步**：API（gRPC/HTTP）
+    - **异步**：事件（Kafka / RabbitMQ / Pulsar）
+
+> 💡 技巧：用 **事件溯源（Event Sourcing） + CQRS** 构建复杂查询视图。
+
+---
+
+### 4. **无状态（Stateless）**
+- 服务实例本身不保存会话或状态（状态存 Redis / DB / Cookie）。
+- 好处：**水平扩展容易**，K8s 可随意扩缩容。
+
+> ⚠️ 例外：批处理、流计算等有状态场景可用 StatefulSet，但要谨慎。
+
+---
+
+### 5. **可观测性（Observability）三件套**
+微服务没有可观测性 = 盲人开车！
+
+| 组件 | 作用 | 工具推荐 |
+|------|------|--------|
+| **Logging** | 记录结构化日志 | Zap / Logrus + Loki / ELK |
+| **Metrics** | 监控性能指标 | Prometheus + Grafana |
+| Assistant | 追踪请求链路 | Jaeger / Zipkin / OpenTelemetry |
+
+> ✅ 必做：
+> - 所有日志带 `trace_id`
+> - 所有 gRPC 调用自动埋点
+> - 关键路径加自定义指标（如“登录成功率”）
+
+---
+
+### 6. **弹性设计（Resilience）**
+网络不可靠！必须假设：
+- 其他服务会宕机
+- 网络会延迟或丢包
+
+✅ 必备机制：
+- **超时（Timeout）**：每个调用设上限（如 1s）
+- **重试（Retry）**：带退避策略（指数退避）
+- **熔断（Circuit Breaker）**：失败太多就短路（如 Hystrix / Sentinel）
+- **限流（Rate Limiting）**：保护自己不被压垮
+- **降级（Fallback）**：返回默认值或缓存数据
+
+> 🛠 Go 推荐库：
+> - `go-resiliency`
+> - `sony/gobreaker`
+> - 自研中间件（结合 context + retry）
+
+---
+
+### 7. **API 优先（API-First Design）**
+- 先定义 `.proto`（gRPC）或 OpenAPI（REST），再写代码。
+- 客户端 SDK 自动生成（如 `protoc-gen-go`）。
+- 版本管理：**向后兼容优先**，避免频繁改接口。
+
+> 📁 目录建议：
+> ```
+> api/
+>   ├── user/v1/user.proto
+>   └── order/v1/order.proto
+> ```
+
+---
+
+### 8. **基础设施即代码（IaC） & GitOps**
+- 数据库、K8s、网关配置全部代码化（Terraform / Helm / Kustomize）。
+- 所有变更通过 Git PR 触发自动化部署。
+- 环境一致性：dev / staging / prod 配置几乎相同。
+
+> ✅ 好处：**“一键重建整个环境”**
+
+---
+
+### 9. **安全内建（Security by Default）**
+- **mTLS**：服务间通信加密（Istio / Linkerd）
+- **RBAC**：基于角色的访问控制
+- **敏感信息**：用 Vault / K8s Secret 管理，不硬编码
+- **输入校验**：所有 API 参数严格验证（如 `validator.v10`）
+
+> 🔒 原则：**“零信任网络”** —— 不信任任何内部流量。
+
+---
+
+### 10. **演进式设计（Evolutionary Architecture）**
+- 不追求“一次性完美架构”
+- 用 **Strangler Fig Pattern（绞杀者模式）** 逐步替换旧系统
+- 定期做 **架构重构** 和 **技术债清理**
+
+> 🌱 微服务是“种出来的”，不是“画出来的”。
+
+---
+
+## 🧱 推荐架构分层（Go 微服务）
+
+```
+user-service/
+├── api/                 # .proto 文件（对外契约）
+├── cmd/                 # main 入口
+├── internal/
+│   ├── handler/         # gRPC/HTTP handlers（薄层）
+│   ├── service/         # 业务逻辑（核心）
+│   ├── repository/      # 数据访问（接口 + mysql 实现）
+│   └── model/           # 领域模型（与 DB 解耦）
+├── pkg/                 # 可共享工具（谨慎！）
+├── deploy/              # K8s / Docker 配置
+└── go.mod
+```
+
+> 🔑 关键：`internal/` 禁止被外部 import，强制通过 API 交互。
+
+---
+
+## 🚫 微服务常见反模式（务必避开！）
+
+| 反模式 | 后果 |
+|-------|------|
+| 分布式单体 | 失去微服务所有优势 |
+| 共享数据库 | 强耦合，无法独立演进 |
+| 同步调用链过长（A→B→C→D） | 故障放大，雪崩风险 |
+| 无监控无告警 | 出问题找不到原因 |
+| 手动部署 | 发布慢，易出错 |
+
+---
+
+## ✅ 最后建议：从小做起，逐步完善
+
+1. **先保证“能跑”**：一个服务 + 独立 DB + gRPC API
+2. **加上可观测性**：日志 + Metrics + Tracing
+3. **加上弹性机制**：超时 + 重试
+4. **加上 CI/CD**：自动化测试 & 部署
+5. **再考虑事件驱动、CQRS、Service Mesh...**
+
+> 🌟 **好的微服务架构不是设计出来的，而是在约束和实践中演化出来的。**
+
+---