# 基于 go-zero 的完整微服务架构设计

## 🏗️ 整体架构图

```
┌─────────────────────────────────────────────────────────┐
│                    External Access                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │Web App  │  │Mobile   │  │3rd API  │  │Admin    │   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘   │
└───────│────────────│─────────────│─────────────│───────┘
        │            │             │             │
        └────────────┼─────────────┼─────────────┘
                     │             │
              ┌──────▼─────────────▼──────┐
              │    Gateway API (HTTP)     │  🌐 HTTP入口
              └──────┬────────────────────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
    ┌────▼────┐ ┌───▼───┐ ┌─────▼─────┐
    │User RPC │ │Data   │ │Admin HTTP │  🔥 核心服务
    │         │ │RPC    │ │           │
    └────┬────┘ └───┬───┘ └─────┬─────┘
         │          │           │
    ┌────▼────┐ ┌───▼───┐ ┌─────▼─────┐
    │Security │ │Billing│ │Audit MQS  │  🛡️ 支撑服务
    │RPC      │ │RPC    │ │           │
    └─────────┘ └───────┘ └───────────┘
```

## 📁 完整目录结构

```
tianyuan-microservice/
├── api/                                    # HTTP API服务
│   ├── gateway/                           # 🌐 API网关 (唯一HTTP入口)
│   │   ├── gateway.api                    # API定义
│   │   ├── gateway.go                     # 启动文件
│   │   ├── etc/
│   │   │   ├── gateway.yaml              # 生产配置
│   │   │   └── gateway-dev.yaml          # 开发配置
│   │   ├── internal/
│   │   │   ├── config/config.go          # 配置结构
│   │   │   ├── handler/                  # HTTP处理器
│   │   │   │   ├── auth/
│   │   │   │   │   ├── loginhandler.go
│   │   │   │   │   └── logouthandler.go
│   │   │   │   ├── data/
│   │   │   │   │   ├── riskhandler.go    # /api/v1/data/risk
│   │   │   │   │   ├── credithandler.go  # /api/v1/data/credit
│   │   │   │   │   └── companyhandler.go # /api/v1/data/company
│   │   │   │   ├── user/
│   │   │   │   │   └── userinfohandler.go
│   │   │   │   └── routes.go             # 路由配置
│   │   │   ├── logic/                    # 业务逻辑 (协调RPC调用)
│   │   │   │   ├── auth/
│   │   │   │   │   └── loginlogic.go
│   │   │   │   ├── data/
│   │   │   │   │   ├── risklogic.go      # 协调data-rpc
│   │   │   │   │   ├── creditlogic.go
│   │   │   │   │   └── companylogic.go
│   │   │   │   └── user/
│   │   │   │       └── userinfologic.go
│   │   │   ├── middleware/               # 中间件
│   │   │   │   ├── authinterceptor.go   # JWT认证
│   │   │   │   ├── ratelimit.go         # 限流
│   │   │   │   └── audit.go             # 审计
│   │   │   ├── svc/servicecontext.go    # 服务上下文 (包含所有RPC客户端)
│   │   │   └── types/types.go           # 请求响应类型
│   │   ├── Dockerfile
│   │   └── k8s/
│   │       └── deployment.yaml
│   │
│   └── admin/                            # 🏢 管理后台 (独立HTTP服务)
│       ├── admin.api
│       ├── admin.go
│       ├── etc/admin.yaml
│       ├── internal/
│       │   ├── handler/
│       │   │   ├── product/
│       │   │   │   ├── createproducthandler.go
│       │   │   │   └── listproducthandler.go
│       │   │   ├── review/
│       │   │   │   └── reviewenterprisehandler.go
│       │   │   └── routes.go
│       │   ├── logic/
│       │   ├── svc/servicecontext.go    # 包含RPC客户端
│       │   └── types/types.go
│       ├── Dockerfile
│       └── k8s/deployment.yaml
│
├── rpc/                                  # RPC微服务集群
│   ├── user/                            # 👥 用户域RPC服务
│   │   ├── user.proto                   # gRPC定义
│   │   ├── user.go                      # 启动文件
│   │   ├── etc/user.yaml               # 配置
│   │   ├── internal/
│   │   │   ├── config/config.go
│   │   │   ├── logic/                   # 业务逻辑
│   │   │   │   ├── auth/
│   │   │   │   │   ├── loginlogic.go
│   │   │   │   │   └── validatetokenlogic.go
│   │   │   │   ├── user/
│   │   │   │   │   ├── getuserinfologic.go
│   │   │   │   │   └── updateuserlogic.go
│   │   │   │   └── enterprise/
│   │   │   │       ├── validateenterpriselogic.go
│   │   │   │       └── getenterpriselogic.go
│   │   │   ├── server/userserver.go     # gRPC服务实现
│   │   │   ├── svc/servicecontext.go    # 服务上下文
│   │   │   └── model/                   # 数据模型
│   │   │       ├── usermodel.go         # 用户表模型
│   │   │       ├── enterprisemodel.go   # 企业表模型
│   │   │       └── vars.go              # 常量定义
│   │   ├── pb/                          # 生成的protobuf文件
│   │   │   ├── user.pb.go
│   │   │   └── user_grpc.pb.go
│   │   ├── Dockerfile
│   │   └── k8s/deployment.yaml
│   │
│   ├── data/                            # 📊 数据服务域RPC服务 (核心协调者)
│   │   ├── data.proto
│   │   ├── data.go
│   │   ├── etc/data.yaml
│   │   ├── internal/
│   │   │   ├── logic/
│   │   │   │   ├── orchestrator/
│   │   │   │   │   └── dataorchestratorlogic.go  # 🔥 核心协调逻辑
│   │   │   │   ├── risk/                         # 原FLXG业务
│   │   │   │   │   ├── riskassessmentlogic.go
│   │   │   │   │   └── riskreportlogic.go
│   │   │   │   ├── credit/                       # 原JRZQ业务
│   │   │   │   │   ├── creditchecklogic.go
│   │   │   │   │   └── credithistorylogic.go
│   │   │   │   ├── company/                      # 原QYGL业务
│   │   │   │   │   ├── companyinfologic.go
│   │   │   │   │   └── companysearchlogic.go
│   │   │   │   └── query/                        # 原IVYZ业务
│   │   │   │       ├── dataquerylogic.go
│   │   │   │       └── batchquerylogic.go
│   │   │   ├── server/dataserver.go
│   │   │   ├── svc/servicecontext.go             # 包含其他RPC客户端
│   │   │   └── external/                         # 外部API客户端
│   │   │       ├── westdex/westdexclient.go     # 西部数据源
│   │   │       ├── baidu/baiduclient.go         # 百度API
│   │   │       └── aliyun/aliyunclient.go       # 阿里云API
│   │   ├── pb/
│   │   ├── Dockerfile
│   │   └── k8s/deployment.yaml
│   │
│   ├── security/                        # 🔐 安全域RPC服务
│   │   ├── security.proto
│   │   ├── security.go
│   │   ├── etc/security.yaml
│   │   ├── internal/
│   │   │   ├── logic/
│   │   │   │   ├── encryption/
│   │   │   │   │   ├── encryptlogic.go
│   │   │   │   │   └── decryptlogic.go
│   │   │   │   ├── whitelist/
│   │   │   │   │   ├── checkwhitelistlogic.go
│   │   │   │   │   └── addwhitelistlogic.go
│   │   │   │   └── secret/
│   │   │   │       ├── generatesecretlogic.go
│   │   │   │       └── validatesecretlogic.go
│   │   │   ├── server/securityserver.go
│   │   │   ├── svc/servicecontext.go
│   │   │   └── model/
│   │   │       ├── whitelistmodel.go            # IP白名单表
│   │   │       └── secretkeymodel.go            # 密钥表
│   │   ├── pb/
│   │   ├── Dockerfile
│   │   └── k8s/deployment.yaml
│   │
│   ├── billing/                         # 💰 计费域RPC服务
│   │   ├── billing.proto
│   │   ├── billing.go
│   │   ├── etc/billing.yaml
│   │   ├── internal/
│   │   │   ├── logic/
│   │   │   │   ├── wallet/
│   │   │   │   │   ├── getbalancelogic.go
│   │   │   │   │   ├── rechargelogic.go
│   │   │   │   │   └── freezelogic.go
│   │   │   │   ├── charge/
│   │   │   │   │   ├── chargelogic.go           # 扣费逻辑
│   │   │   │   │   ├── refundlogic.go          # 退费逻辑
│   │   │   │   │   └── calculatelogic.go       # 计费计算
│   │   │   │   └── order/
│   │   │   │       ├── createorderlogic.go
│   │   │   │       └── queryorderlogic.go
│   │   │   ├── server/billingserver.go
│   │   │   ├── svc/servicecontext.go
│   │   │   └── model/
│   │   │       ├── walletmodel.go               # 钱包表
│   │   │       ├── transactionmodel.go          # 交易记录表
│   │   │       └── ordermodel.go                # 订单表
│   │   ├── pb/
│   │   ├── Dockerfile
│   │   └── k8s/deployment.yaml
│   │
│   ├── product/                         # 🛍️ 产品域RPC服务
│   │   ├── product.proto
│   │   ├── product.go
│   │   ├── etc/product.yaml
│   │   ├── internal/
│   │   │   ├── logic/
│   │   │   │   ├── product/
│   │   │   │   │   ├── createproductlogic.go
│   │   │   │   │   ├── getproductlogic.go
│   │   │   │   │   └── updateproductlogic.go
│   │   │   │   ├── access/
│   │   │   │   │   ├── checkproductaccesslogic.go
│   │   │   │   │   └── grantaccesslogic.go
│   │   │   │   └── subscription/
│   │   │   │       ├── subscribelogic.go
│   │   │   │       └── unsubscribelogic.go
│   │   │   ├── server/productserver.go
│   │   │   ├── svc/servicecontext.go
│   │   │   └── model/
│   │   │       ├── productmodel.go              # 产品表
│   │   │       ├── userproductmodel.go          # 用户产品关系表
│   │   │       └── productaccessmodel.go        # 产品权限表
│   │   ├── pb/
│   │   ├── Dockerfile
│   │   └── k8s/deployment.yaml
│   │
│   └── audit/                           # 📝 审计域RPC服务
│       ├── audit.proto
│       ├── audit.go
│       ├── etc/audit.yaml
│       ├── internal/
│       │   ├── logic/
│       │   │   ├── apilog/
│       │   │   │   ├── recordapiloglogic.go
│       │   │   │   └── queryapiloglogic.go
│       │   │   ├── operation/
│       │   │   │   ├── recordoperationlogic.go
│       │   │   │   └── queryoperationlogic.go
│       │   │   └── statistics/
│       │   │       ├── apistatslogic.go
│       │   │       └── usagestatslogic.go
│       │   ├── server/auditserver.go
│       │   ├── svc/servicecontext.go
│       │   └── model/
│       │       ├── apilogmodel.go              # API调用日志表
│       │       ├── operationlogmodel.go        # 操作日志表
│       │       └── statisticsmodel.go          # 统计数据表
│       ├── pb/
│       ├── Dockerfile
│       └── k8s/deployment.yaml
│
├── mqs/                                 # 📮 消息队列服务
│   ├── consumer/                        # 消息消费者
│   │   ├── audit/                       # 审计消息消费
│   │   │   ├── auditconsumer.go
│   │   │   └── etc/auditconsumer.yaml
│   │   ├── billing/                     # 计费消息消费
│   │   │   ├── billingconsumer.go
│   │   │   └── etc/billingconsumer.yaml
│   │   └── notification/                # 通知消息消费
│   │       ├── notificationconsumer.go
│   │       └── etc/notificationconsumer.yaml
│   └── producer/                        # 消息生产者 (在各RPC服务中)
│
├── shared/                              # 🔧 共享库
│   ├── pkg/
│   │   ├── crypto/                      # 加密工具
│   │   │   ├── aes.go
│   │   │   └── rsa.go
│   │   ├── jwt/                         # JWT工具
│   │   │   └── jwt.go
│   │   ├── response/                    # 统一响应格式
│   │   │   └── response.go
│   │   ├── errors/                      # 错误定义
│   │   │   └── errors.go
│   │   ├── utils/                       # 工具函数
│   │   │   ├── strings.go
│   │   │   └── time.go
│   │   └── middleware/                  # 公共中间件
│   │       ├── recovery.go
│   │       └── prometheus.go
│   ├── model/                           # 公共数据模型
│   │   ├── common.go                    # 通用字段
│   │   └── pagination.go               # 分页模型
│   └── proto/                           # 公共protobuf定义
│       └── common.proto
│
├── deploy/                              # 🚀 部署相关
│   ├── docker/
│   │   ├── docker-compose.dev.yml      # 开发环境
│   │   ├── docker-compose.prod.yml     # 生产环境
│   │   └── nginx/                       # Nginx配置
│   │       └── nginx.conf
│   ├── k8s/                            # Kubernetes部署
│   │   ├── namespace.yaml
│   │   ├── configmap.yaml
│   │   ├── mysql.yaml
│   │   ├── redis.yaml
│   │   ├── kafka.yaml
│   │   ├── etcd.yaml
│   │   └── ingress.yaml
│   ├── terraform/                       # 基础设施即代码
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── scripts/                         # 部署脚本
│       ├── build.sh                     # 构建脚本
│       ├── deploy.sh                    # 部署脚本
│       └── migrate.sh                   # 数据库迁移脚本
│
├── tools/                               # 🛠️ 开发工具
│   ├── goctl/                          # go-zero代码生成工具配置
│   │   ├── api.tpl                     # API模板
│   │   └── rpc.tpl                     # RPC模板
│   ├── migrate/                        # 数据库迁移工具
│   │   ├── migrations/
│   │   │   ├── 001_create_users.sql
│   │   │   ├── 002_create_enterprises.sql
│   │   │   ├── 003_create_products.sql
│   │   │   ├── 004_create_wallets.sql
│   │   │   └── 005_create_audit_logs.sql
│   │   └── migrate.go
│   └── generate/                       # 代码生成脚本
│       ├── gen-api.sh                  # 生成API代码
│       ├── gen-rpc.sh                  # 生成RPC代码
│       └── gen-model.sh                # 生成Model代码
│
├── docs/                               # 📚 项目文档
│   ├── api/                           # API文档
│   │   ├── gateway.md
│   │   └── admin.md
│   ├── rpc/                           # RPC服务文档
│   │   ├── user.md
│   │   ├── data.md
│   │   └── billing.md
│   ├── database/                      # 数据库设计文档
│   │   ├── schema.md
│   │   └── erd.md
│   └── deployment/                    # 部署文档
│       ├── k8s.md
│       └── docker.md
│
├── .github/                           # 🔄 CI/CD
│   └── workflows/
│       ├── api-gateway.yml
│       ├── user-rpc.yml
│       ├── data-rpc.yml
│       └── deploy.yml
│
├── go.work                            # Go工作区配置
├── Makefile                           # 统一构建脚本
├── README.md                          # 项目说明
└── .gitignore                         # Git忽略文件
```

## 🎯 服务分类与职责

### HTTP 服务 (对外接口)

-   **gateway**: 唯一 HTTP 入口，负责路由和协调
-   **admin**: 管理后台，企业管理、产品管理、审核等

### RPC 服务 (内部通信)

-   **user**: 用户、企业、认证管理
-   **data**: 数据服务协调器 + 原有业务逻辑
-   **security**: 加密解密、白名单、密钥管理
-   **billing**: 钱包、计费、订单管理
-   **product**: 产品、权限、订阅管理
-   **audit**: 日志记录、统计分析

### MQS 服务 (异步处理)

-   **audit-consumer**: 异步处理审计日志
-   **billing-consumer**: 异步处理计费通知
-   **notification-consumer**: 异步处理消息通知

## 💾 数据库设计

### 按域分库

```yaml
databases:
    user_db: # 用户域数据库
        tables:
            - users
            - enterprises
            - user_tokens

    security_db: # 安全域数据库
        tables:
            - ip_whitelist
            - secret_keys
            - encrypt_records

    billing_db: # 计费域数据库
        tables:
            - wallets
            - transactions
            - orders
            - billing_records

    product_db: # 产品域数据库
        tables:
            - products
            - user_products
            - product_access

    audit_db: # 审计域数据库
        tables:
            - api_logs
            - operation_logs
            - statistics
```

接下来我会详细说明每个部分的具体实现...