Web 平台開發日記 - 第一章：從零開始的架構設計與技術選型

系列導讀: 本系列記錄了個人實戰項目的完整開發過程。通過結合自己掌握的技術棧，完整記錄從設計、架構、實現到部署的全過程，並總結開發中的經驗教訓。

項目性質: 個人開源學習項目
當前階段: 基礎框架與基礎設施（已完成）

一、項目背景

1.1 項目初心

這是個人實戰項目，主要目的是：

• 🎯 技術實踐 - 結合自己掌握的技術棧（Go + Vue 3）進行深度實踐
• 📝 記錄過程 - 完整記錄從設計、架構、實現到部署的全過程
• 🧪 測試框架 - 在一個完整的項目中驗證各種技術選擇的可行性
• 📚 學習總結 - 通過博客系列分享開發過程中的經驗教訓

1.2 項目定位

項目名稱: Enterprise Web Platform (EWP)\
項目性質: 開源、學習、實戰\
技術棧: Go 1.22 + Vue 3 + MySQL 8.4 + Redis 7\
目標: 構建一個具有企業級特性的完整 Web 應用平台

這不是為了商業用途，而是為了在實際開發中深入理解：

• 如何從零開始設計應用架構
• 如何做出合理的技術選型決策
• 如何搭建完整的開發、部署、監控體系
• 如何編寫可維護、可擴展的代碼

1.3 核心特點

二、技術選型

技術選型是項目成功的基礎。我們的選型過程遵循了"需求驅動"的原則，即：先明確需求，再根據需求評估候選方案。

2.1 選型評估框架

我們建立了一個多維度的評估框架：

選型評估 = 需求滿足度 + 生態完善度 + 學習成本 + 長期維護性 + 許可證合規性

2.2 後端技術選型

📋 核心需求

• 支持 RESTful API 快速開發
• ORM 能力完善（自動遷移、關聯查詢等）
• 內置中間件系統（認證、CORS、日誌等）
• 熱部署支持（開發階段）
• 性能優異

🎯 候選方案評估

方案 A: 使用現成的完整項目模板

優點: ✅ 功能完善，開發快速
優點: ✅ 文檔豐富，社區活躍
缺點: ❌ 通常包含授權限制或商業條款
缺點: ❌ 定製空間有限，架構固定
缺點: ❌ 難以理解底層設計細節
結論: 對於學習和深度定製不合適 ✗

方案 B: Go Web 框架選型

我重點對比了三個主流的 Go Web 框架：

Gin 框架深入分析 ✅

// 簡潔的路由定義
func main() {
    router := gin.Default()
    
    // 基本路由
    router.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    
    // 路由組
    v1 := router.Group("/api/v1")
    {
        v1.POST("/users", createUser)
        v1.GET("/users/:id", getUser)
    }
    
    router.Run(":8080")
}

選擇 Gin 的原因:

• 🏆 Go 社區中最流行和成熟的框架
• ⚡ 性能在三者之間均衡（足夠快，但不過度優化）
• 📚 文檔最完善，教程和案例最多
• 🔧 中間件系統完整，易於擴展
• 🏢 企業級應用最廣泛（字節跳動、小米等都在用）
• 🎯 學習成本最低，對初學者友好
• 📦 與 GORM、Viper 等庫的集成最成熟

Fiber vs Gin:

Fiber 的優勢:
  ✅ 性能最高（基於 Fasthttp，併發能力最強）
  ✅ Express.js 風格，對 Node.js 開發者友好
  ✅ 開發速度快，API 簡潔直觀

Fiber 的劣勢:
  ❌ 社區相對較小
  ❌ 文檔和教程相對較少
  ❌ 與其他 Go 庫的生態集成度不如 Gin
  ❌ 在中等併發下，性能優勢不明顯

Echo vs Gin:

Echo 的優勢:
  ✅ 高性能（與 Gin 相當）
  ✅ 中間件系統完整
  ✅ 數據綁定和驗證功能強大

Echo 的劣勢:
  ❌ 社區規模和熱度不如 Gin
  ❌ 文檔質量一般
  ❌ 在國內使用較少，遇到問題難以找到解決方案

最終結論:

對於這個項目，選擇 Gin 是最優選擇，因為：
1. 最成熟穩定，適合學習和參考
2. 社區最活躍，問題最容易解決
3. 文檔最完善，教程資源最豐富
4. 與 Go 生態庫的集成最好
5. 對後期維護和擴展最有利

方案 C: 完全自定義框架

優點: ✅ 最大靈活性
缺點: ❌ 開發週期長（6+ 個月）
缺點: ❌ 重複發明輪子
缺點: ❌ 維護成本高，容易埋坑
結論: 對於學習項目不經濟 ✗

最終技術棧選擇 ✅

後端框架: Gin (MIT)
  ✅ Go 生態中最成熟的 Web 框架
  ✅ 完整的中間件支持
  ✅ 高性能且性能均衡
  ✅ 活躍的社區和豐富的教程
  
ORM: GORM v2 (MIT)
  ✅ Go 最完善的 ORM 框架
  ✅ 自動遷移功能（省去手寫 SQL）
  ✅ 強大的關聯查詢能力
  ✅ 企業級生產應用廣泛使用
  
認證: golang-jwt/jwt (MIT)
  ✅ JWT 標準實現
  ✅ 支持多種算法
  ✅ 生態成熟
  
授權: Casbin (Apache 2.0 無商業限制)
  ✅ 支持 RBAC、ABAC 等多種模型
  ✅ 靈活的權限定義
  ✅ 高效的策略匹配

📊 後端選型總結

2.3 前端技術選型

📋 核心需求

• 現代化的開發體驗（熱更新、TypeScript 支持）
• 企業級 UI 組件庫
• 權限管理和動態菜單
• 完善的管理後台模板
• 零許可證限制

🎯 候選方案評估

方案 A: Vue Pure Admin（最終選擇）✅

Vue Pure Admin 是一款基於 Vue 3、Vite、Element-Plus、TypeScript 等最新技術棧開發的中後台管理系統模板。

技術棧:

• ✅ Vue 3（核心框架）- 最新的 Vue 版本，Composition API
• ✅ Element Plus（UI 庫）- 國內最流行的企業級組件庫
• ✅ Vite（構建工具）- 極速開發體驗和優化的生產構建
• ✅ Pinia（狀態管理）- Vue 3 官方推薦的狀態管理庫
• ✅ Vue Router（路由）- 支持動態路由、權限控制
• ✅ TypeScript - 完整的類型支持，提高代碼質量
• ✅ Tailwind CSS - 實用優先的 CSS 框架

為什麼選它:

• ✅ 開箱即用 - 包含登錄、權限、菜單、表格等完整的後台管理功能
• ✅ 生產級代碼 - 遵循企業級最佳實踐，代碼規範清晰
• ✅ 快速上手 - 作為後端開發者，可以直接使用框架邊開發邊學習前端
• ✅ 完整示例 - 提供了豐富的業務組件和使用案例
• ✅ 活躍維護 - 社區活躍，持續更新和改進
• ✅ 靈活定製 - 架構清晰，易於擴展和定製
• ✅ 適合團隊協作 - 代碼結構規範，新開發者易上手

結論: 對於以後端開發為主、希望快速搭建管理後台的項目，Vue Pure Admin 是最佳選擇 ✓

📊 其他前端框架對比

關鍵區別:

1. Vue Pure Admin vs 從零搭建

   • Vue Pure Admin: 生產級代碼，包含完整功能，適合快速交付
   • 從零搭建: 學習價值最高，但開發週期長

2. Vue Pure Admin vs Ant Design Vue

   • Vue Pure Admin 使用 Element Plus（國內常用）
   • Ant Design Vue 使用 Ant Design（國際化風格）
   • Vue Pure Admin 更輕量，Ant Design 功能更全面

3. Vue Pure Admin vs Vben Admin

   • Vue Pure Admin: 相對輕量級，易上手
   • Vben Admin: 功能更強大，但複雜度更高

📊 前端選型總結

2.4 基礎設施選型

數據庫

MySQL 8.4（升級從 5.7）

原本選擇 MySQL 5.7，但開發環境為 Apple Silicon (ARM64)
❌ MySQL 5.7 不支持 ARM64 架構
✅ 升級到 MySQL 8.4 完全支持 ARM64
✅ 8.4 向後兼容 5.7，無遷移成本
✅ 更好的性能和安全特性

Redis 7

✅ 支持 ARM64
✅ 性能改進（Stream 增強等）
✅ 廣泛使用的緩存和會話存儲

容器化與編排

Podman（替代 Docker）

為什麼選擇 Podman？

安全優勢:

• ✅ 無需 root 權限（Rootless 容器）- 權限提升風險更低
• ✅ 無守護進程 - 沒有以 root 身份運行的後台服務
• ✅ 進程隔離模型 - 單一容器出現問題不影響其他容器

運維優勢:

• ✅ 資源消耗少 - 無後台守護進程，內存佔用更低
• ✅ 輕量級 - 適合開發機和邊緣部署
• ✅ Kubernetes 原生支持 - Pod 概念直接映射到 K8s
• ✅ 100% 開源 - RedHat 維護，無商業許可限制

開發體驗:

• ✅ 與 Docker API 完全兼容 - 所有 Docker 命令無需改動
• ✅ 支持 Podman Compose - 等同於 Docker Compose
• ✅ 更清晰的進程模型 - 便於理解容器生命週期

Docker 作為備選方案:

• ⚠️ 需要 root 權限或 Docker 守護進程 - 提升權限風險
• ⚠️ 後台守護進程 - 即使不使用也消耗系統資源
• ⚠️ Docker Desktop 商業許可 - macOS/Windows 有企業許可考慮
• ✅ 但仍完全支持（make docker-up）

實際對比:

安裝:

# macOS
brew install podman podman-compose
podman machine init
podman machine start

# Linux (Ubuntu/Debian)
sudo apt-get install podman podman-compose

# 驗證安裝
podman --version
podman ps

遷移到 Podman 很簡單:

# 如果之前使用 Docker
make docker-down      # 停止 Docker 容器

# 改用 Podman
make podman-up        # 啓動 Podman 容器

# 兩者的命令完全相同，配置文件也相同

監控與可觀測性

Prometheus + Grafana

✅ 開源免費
✅ 業界標準的監控方案
✅ 完全自託管（數據不離開客户基礎設施）
✅ 支持本地部署

其他考慮
❌ SaaS 方案（Datadog、New Relic）：數據隱私和成本問題
❌ 雲原生方案（雲平台內置監控）：廠商鎖定風險

API 網關

Nginx

✅ 業界標準，久經考驗
✅ 開源免費
✅ 功能完善（SSL、限流、緩存等）
✅ 高性能低資源消耗

其他考慮
- Kong（更功能豐富但複雜度高）
- Traefik（Kubernetes 原生但不適合初期）

2.5 許可證合規性保證

這是選型中最關鍵的一環。選型的許可證檢查清單：

依賴檢查清單
├── 後端依賴
│   ├── MIT: Gin, GORM, Zap, Viper, jwt-go, Validator ✅
│   ├── Apache 2.0 (無商業限制): Casbin, Prometheus ✅
│   ├── BSD: Redis ✅
│   └── ❌ GPL: 零個
├── 前端依賴
│   ├── MIT: Vue, Vue Router, Pinia, Element Plus, Vite, Axios ✅
│   └── ❌ GPL: 零個
└── 基礎設施
    ├── BSD: Nginx, Redis ✅
    ├── Apache 2.0: Docker, Prometheus ✅
    └── ❌ GPL: 零個

結論: ✅ 100% 許可證合規，零商業限制

三、項目架構：整體設計與模塊介紹

3.1 整體架構圖

┌─────────────────────────────────────────────────────────────┐
│                     客户端瀏覽器                              │
│              (Vue 3 + Element Plus SPA)                      │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTPS
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   Nginx API Gateway                           │
│  • SSL/TLS 終止                                              │
│  • 靜態資源服務 (前端 SPA)                                    │
│  • API 請求代理                                              │
│  • 速率限制和安全頭                                           │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Gin Web 框架 (Go 後端)                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 中間件層                                             │   │
│  │ • CORS 處理                                          │   │
│  │ • JWT 認證                                           │   │
│  │ • Casbin RBAC 授權                                   │   │
│  │ • 結構化日誌 (Zap)                                    │   │
│  │ • Prometheus 指標收集                                │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 路由處理層 (api/v1/*)                                │   │
│  │ • 認證管理 (/auth/login, /auth/logout)             │   │
│  │ • 用户管理 (/users/*, /roles/*)                    │   │
│  │ • 文件管理 (/files/upload, /files/download)        │   │
│  │ • 健康檢查 (/health, /ready, /metrics)             │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 業務邏輯層 (service/*)                               │   │
│  │ • 用户服務                                            │   │
│  │ • 權限服務                                            │   │
│  │ • 文件服務                                            │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 數據模型層 (model/*)                                 │   │
│  │ • User (用户)                                        │   │
│  │ • Role (角色)                                        │   │
│  │ • Permission (權限)                                  │   │
│  │ • BaseModel (創建時間、更新時間等)                    │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────┬────────────────────────────────┬────────────────┘
             │                                │
             ▼ 讀寫                           ▼ 緩存
    ┌─────────────────────┐         ┌─────────────────────┐
    │   MySQL 8.4         │         │   Redis 7           │
    │                     │         │                     │
    │ • 業務數據存儲        │         │ • 會話存儲           │
    │ • 用户認證信息        │         │ • 緩存數據           │
    │ • 權限關係           │         │ • 併發控制           │
    └─────────────────────┘         └─────────────────────┘

3.2 分層架構詳解

我們採用了經典的三層架構 + 中間件 設計：

第一層：路由與中間件層 (router/ 和 middleware/)

職責:

• 接收 HTTP 請求
• 執行跨越多個處理器的操作（認證、日誌、限流等）
• 路由分發

關鍵文件:

server/
├── router/
│   └── router.go          # 路由註冊
├── middleware/
│   ├── cors.go            # 跨域資源共享
│   ├── jwt.go             # JWT 認證 (待實現)
│   ├── rbac.go            # Casbin 授權 (待實現)
│   ├── logger.go           # 結構化日誌 (待實現)
│   └── metrics.go          # Prometheus 指標 (待實現)

核心職責是接收 HTTP 請求、應用中間件（CORS、認證、日誌等）、分發到對應的處理器。

第二層：業務邏輯層 (service/)

職責:

• 實現具體的業務邏輯
• 與數據模型交互
• 獨立於 HTTP 框架（可複用於 gRPC、CLI 等）

關鍵文件:

server/service/
├── user_service.go        # 用户相關業務邏輯
├── auth_service.go        # 認證相關業務邏輯
├── role_service.go        # 角色權限業務邏輯
└── file_service.go        # 文件上傳下載業務邏輯

業務邏輯層獨立於 HTTP 框架，包含實際的業務規則：數據驗證、密碼加密、緩存更新等。

第三層：數據模型層 (model/)

職責:

• 定義數據結構
• 與數據庫表映射
• 包含 GORM 標籤和驗證規則

關鍵文件:

server/model/
├── base.go                # 基礎模型（id、創建時間等）
├── user.go                # 用户模型
├── role.go                # 角色模型
├── permission.go          # 權限模型
└── file.go                # 文件模型

數據模型層使用 GORM 標籤定義數據庫表結構、關聯關係和字段驗證規則。

3.3 關鍵模塊深入

📌 認證模塊 (JWT)

流程:

1. 用户登錄時，後端驗證用户名/密碼
2. 驗證成功後，生成包含用户 ID 和權限的 JWT token
3. 前端將 token 存儲在 localStorage
4. 後續請求在 Authorization Header 中攜帶 token
5. 中間件驗證 token 的有效性和簽名

JWT 實現包括 token 生成（包含用户 ID、用户名、角色）和驗證（驗證簽名和過期時間）。

📌 授權模塊 (Casbin RBAC)

RBAC 模型定義 (config/rbac_model.conf):

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

權限規則定義簡潔（例如：p, admin, /users/*, *），中間件通過 Casbin 驗證用户是否有權訪問特定資源。

📌 結構化日誌模塊 (Zap)

目的:

• 便於日誌聚合和分析
• 包含請求 ID 便於追蹤
• 性能高效

結構化日誌以 JSON 格式輸出，包含日誌級別、時間戳、調用位置和自定義字段，便於日誌聚合和分析。

3.4 前端架構

前端採用 Vue Pure Admin 框架，這是一款基於 Vue 3 + Element Plus + Vite 的企業級管理後台模板。

核心特點:

• 開箱即用 - 包含完整的登錄、權限管理、菜單系統、表格等功能
• 現代化技術棧 - Vue 3 Composition API、TypeScript、Vite 構建
• 企業級規範 - 代碼結構清晰，遵循最佳實踐
• 易於上手 - 作為後端開發者，可以直接修改和擴展
• 生產級質量 - 經過驗證的架構和最佳實踐

項目結構 - Vue Pure Admin 標準結構：

web/
├── src/
│   ├── api/                    # API 服務層 (Axios 請求)
│   ├── views/                  # 頁面組件 (登錄、儀表板、管理等)
│   ├── components/             # 可複用的業務組件
│   ├── layout/                 # 佈局組件 (菜單、頂欄等)
│   ├── router/                 # 路由配置 + 權限控制
│   ├── store/                  # Pinia 狀態管理
│   ├── utils/                  # 工具函數 (HTTP、存儲等)
│   ├── types/                  # TypeScript 類型定義
│   ├── App.vue                 # 根組件
│   └── main.ts                 # 應用入口
├── index.html                  # HTML 模板
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── package.json                # 依賴管理

關鍵功能:

• ✅ 權限控制 - 基於角色的訪問控制 (RBAC)
• ✅ 動態菜單 - 支持權限級別的菜單顯示/隱藏
• ✅ 主題切換 - 內置亮色和暗黑主題
• ✅ 響應式設計 - 支持 PC、平板、手機多種設備
• ✅ 完整的管理功能 - 用户管理、角色管理、權限管理等

四、項目現狀

4.1 開發環境部署

經過第一階段的開發，我們成功搭建了完整的開發環境：

📦 基礎設施啓動狀態

$ make podman-up
✅ MySQL 8.4:     localhost:3306 (container: ewp-mysql)
✅ Redis 7:       localhost:6379 (container: ewp-redis)
✅ Prometheus:    localhost:9090 (container: ewp-prometheus)
✅ Grafana:       localhost:3000 (container: ewp-grafana)

提示: 所有容器都帶有 ewp- 前綴（Enterprise Web Platform 的縮寫），方便在本地開發環境中識別和管理。

🚀 後端服務

$ make run-backend
2025-12-24T17:26:19.324+0800  INFO  Server starting...
2025-12-24T17:26:19.354+0800  INFO  Database connected successfully
2025-12-24T17:26:19.360+0800  INFO  Redis connected successfully
✅ Backend:       http://localhost:8888

已實現的 API 端點:

🎨 前端應用

$ make run-frontend
  VITE v7.1.12  ready in 1016 ms

  ➜  Local:   http://localhost:8848/

4.2 項目效果圖

系統現已部署在本地

後端啓動日誌

前端啓動日誌

容器運行狀態

4.3 技術債清單

當前已完成的工作中，以下項目需要在後續階段完善：

• [ ] 單元測試（後端 service 層）
• [ ] 集成測試（API 端點）
• [ ] 前端組件測試
• [ ] 端到端測試 (E2E)
• [ ] 性能基準測試
• [ ] 安全審計
• [ ] 代碼覆蓋率報告

五、後續開發方向與計劃

5.1 開發計劃概覽

項目按照功能特性分為幾個主要階段進行開發：

Phase 1: 基礎框架與基礎設施    ✅ 已完成
  ├─ 項目腳手架和包結構
  ├─ 框架集成（Gin、GORM、Viper 等）
  └─ 基礎設施搭建（MySQL、Redis、Prometheus、Grafana）

Phase 2: 認證與授權體系         📝 開發中
  ├─ JWT 認證完整實現
  ├─ Casbin RBAC 權限管理
  ├─ 用户和角色管理 API
  └─ 前端權限控制和動態菜單

Phase 3: 核心功能模塊          📝 計劃中
  ├─ CRUD 基礎操作
  ├─ 文件上傳下載
  ├─ 數據導入導出
  └─ 常用工具函數

Phase 4: 企業級特性            📝 計劃中
  ├─ 完整的監控體系
  ├─ 結構化日誌系統
  ├─ API 文檔（Swagger）
  └─ 性能優化

Phase 5: 部署與運維            📝 計劃中
  ├─ 單機部署方案
  ├─ 多機部署方案
  ├─ 容器化部署
  └─ 高可用配置

Phase 6: 測試與質量保證        📝 計劃中
  ├─ 單元測試
  ├─ 集成測試
  ├─ 性能測試
  └─ 安全審計

Phase 7: 文檔與總結            📝 計劃中
  ├─ 完整的項目文檔
  ├─ 最佳實踐總結
  └─ 技術經驗分享

這個計劃是靈活的，會根據實際情況進行調整。每個階段的重點是確保代碼質量和完整的學習記錄。

常見問題

Q: MySQL 連接失敗？
A: 確保容器已啓動 podman ps，檢查 config.yaml 中的 host 是否為 localhost

Q: 前端無法連接後端？
A: 檢查 vite.config.js 中的代理配置，或在瀏覽器 F12 檢查 Network 標籤

Q: Podman 命令找不到？
A: 使用 pipx install podman-compose 安裝（macOS 可用 Homebrew）