跳至主要内容

貢獻指南

如何參與 AppFuse Server 的開發

開發環境設定​

系統需求​

項目版本
Java21+
Gradle8.x
IDEIntelliJ IDEA（推薦）

建構專案​

# Clone 專案
git clone <repository-url>
cd appfuse-server

# 建構
./gradlew build

# 執行測試
./gradlew test

開發流程​

1. 功能提案​

在開始開發之前：

  1. 在 Issues 中提出功能建議
  2. 說明使用場景和預期 API
  3. 等待社群討論和批准

2. 分支管理​

# 建立功能分支
git checkout -b feature/your-feature-name

# 開發完成後
git push origin feature/your-feature-name

3. 提交規範​

遵循 Conventional Commits：

<type>(<scope>): <subject>

<body>

Type 類型:

Type說明
feat新增功能
fix修復 bug
docs文檔更新
refactor重構
test測試
chore雜項維護

範例:

feat(cache): 新增雙層快取功能

實作 DualLayerCache，支援快速層和持久層的自動降級查詢。

4. Pull Request​

  1. 確保所有測試通過
  2. 更新相關文檔
  3. 提交 PR 並等待 Code Review

程式碼規範​

Java 風格​

  • 使用 4 空格縮排
  • 類別名稱使用 PascalCase
  • 方法和變數使用 camelCase
  • 常數使用 UPPER_SNAKE_CASE

文檔規範​

  • 所有 public 類別和方法需有 JavaDoc
  • 註解使用繁體中文
  • 錯誤訊息和日誌使用英文

測試規範​

  • 測試覆蓋率目標 > 80%
  • 使用 JUnit 5
  • 測試類別命名：{ClassName}Test

模組開發指南​

新增功能模組​

  1. 在 app-server 中驗證

    • 先在參考實作中開發和測試
    • 確認功能穩定且通用

  2. 提取到框架

    • 抽象化介面
    • 移除業務邏輯依賴
    • 確保通用性

  3. 撰寫文檔

    • 使用指南：appfuse-docs/docs-server/guides/{module}.md
    • API 參考：appfuse-docs/docs-server/api/{module}.md

  4. 更新索引

    • 更新 sidebars-server.ts
    • 更新 PROGRESS.md

目錄結構​

appfuse-server/
├── src/main/java/              # 原始碼
│   └── io/leandev/appfuse/
│       ├── cache/
│       ├── csv/
│       ├── http/
│       └── ...
│
├── src/test/java/              # 測試
│   └── io/leandev/appfuse/
│
├── docs/                       # 指引文檔（指向 appfuse-docs）
│   ├── AGENTS.md
│   └── INDEX.md
│
├── README.md
├── CHANGELOG.md
└── AGENTS.md

appfuse-docs/                   # 統一文檔站
├── docs-server/
│   ├── guides/                 # 使用指南
│   ├── api/                    # API 參考
│   └── development/            # 開發指南

發佈流程​

版本號規範​

遵循 語義化版本：

主版本號.次版本號.修訂號

- 主版本號：不相容的 API 變更
- 次版本號：向後相容的功能新增
- 修訂號：向後相容的問題修正

發佈步驟​

  1. 更新 CHANGELOG.md
  2. 更新版本號
  3. 建立 Git tag
  4. 發佈到 Maven Repository

聯絡方式​

  • Issues: 提交問題或建議
  • Pull Requests: 提交程式碼貢獻