[iDempiere] Plugin 開發入門：用 OSGi 擴充 iDempiere 而不改核心

小編 2026/02/072026/02/07 發佈留言

本篇文章更新時間：2026/02/07
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知或向一介資男的 LINE 社群反應。
如果本站內容對你有幫助，歡迎贊助支持。

iDempiere 最強大的設計之一，就是透過 OSGi Plugin 架構讓你可以擴充功能而完全不需要修改核心原始碼。這篇文章介紹 Plugin 開發的基本概念、開發環境設定和第一個 Plugin 的實作方向。

這是 iDempiere 開源 ERP 系列文章 的第 13 篇。如果你還沒有設定好開發環境，可以先參考我的文章〈[iDempiere] 開源 ERP 的編譯與執行〉和〈[iDempiere] Mac 開發環境建置 2025 年 OpenJDK 23 版本〉。

內容目錄

1 為什麼不應該直接改原始碼
2 OSGi 基本概念
3 開發環境設定
- 3.1 必要工具
- 3.2 設定步驟概要
4 第一個 Plugin：自訂 Process
5 2Pack：打包與部署
- 5.1 2Pack 的用途
6 REST API 整合
7 Plugin 開發最佳實踐
8 小結
- 8.1 iDempiere 開源 ERP 系列文章（完整目錄）
9 參考資料

為什麼不應該直接改原始碼

在 ADempiere 時代，客製化通常意味著直接修改核心原始碼。這帶來了嚴重的問題：

升級地獄：每次核心版本升級，都要把自己的修改重新合併，衝突不斷
維護噩夢：時間一久，改了哪些地方、為什麼改，很快就失去追蹤
多人協作困難：不同團隊的修改互相衝突

iDempiere 的 OSGi Plugin 架構從根本上解決了這些問題：你的客製化程式碼獨立存在於自己的 Plugin 中，核心升級時只需確保 Plugin 的介面相容性。

OSGi 基本概念

OSGi（Open Services Gateway initiative）是一套 Java 模組化框架。在 iDempiere 中，它的核心概念是：

Bundle（套件包）

每個 Plugin 就是一個 OSGi Bundle
Bundle 有自己的類別路徑和相依關係
Bundle 有生命週期：INSTALLED → RESOLVED → STARTING → ACTIVE → STOPPING

Service（服務）

Bundle 之間透過「服務」溝通
遵循 Publish-Find-Bind 模式
一個 Bundle 可以發布服務，其他 Bundle 可以查找和使用這些服務

Extension Point（擴充點）

iDempiere 定義了許多擴充點，讓 Plugin 可以「插入」到核心的特定位置：

Model Validator：在文件保存、完成等事件時執行自訂邏輯
Callout：欄位值變更時觸發的即時邏輯
Process：自訂的批次處理流程
Form：自訂的表單介面
Event Handler：監聽系統事件

開發環境設定

必要工具

Eclipse IDE for Enterprise Java Developers（建議 2025-09 版本）
OpenJDK 17+
Maven
Git

設定步驟概要

Clone iDempiere 原始碼：git clone https://github.com/idempiere/idempiere.git
匯入 Eclipse：使用 File → Import → Existing Projects 匯入
設定 Target Platform：iDempiere 自帶 Target Platform 定義
建立資料庫並匯入種子資料
執行 iDempiere 確認開發環境正常運作

詳細的開發環境設定步驟，請參考 iDempiere Software Developer's Guide 和我的系列文章。

第一個 Plugin：自訂 Process

以建立一個簡單的自訂 Process（批次處理流程）為例，說明 Plugin 開發的基本結構。

Plugin 專案結構

com.yourcompany.idempiere.myplugin/
├── META-INF/
│   └── MANIFEST.MF          # OSGi Bundle 描述檔
├── OSGI-INF/
│   └── MyProcess.xml         # OSGi Service 定義
├── src/
│   └── com/yourcompany/
│       └── process/
│           └── MyProcess.java  # 自訂 Process 程式碼
├── build.properties
└── pom.xml                   # Maven 建構檔

MANIFEST.MF 重點

Bundle-Name: My Custom Plugin
Bundle-SymbolicName: com.yourcompany.idempiere.myplugin;singleton:=true
Bundle-Version: 1.0.0
Require-Bundle: org.adempiere.base;bundle-version="12.0.0"
Service-Component: OSGI-INF/*.xml

自訂 Process 骨架

package com.yourcompany.process;

import org.compiere.process.SvrProcess;

public class MyProcess extends SvrProcess {

    @Override
    protected void prepare() {
        // 讀取參數
    }

    @Override
    protected String doIt() throws Exception {
        // 商業邏輯
        return "Process completed successfully";
    }
}

2Pack：打包與部署

2Pack 是 iDempiere 的資料打包工具，可以把 Application Dictionary 的修改（新增的視窗、欄位、流程定義等）打包成 XML 格式，方便在不同環境之間遷移。

2Pack 的用途

將 Plugin 相關的 AD 設定（視窗、欄位、Menu 等）打包
在測試環境和正式環境之間遷移設定
發布 Plugin 時附帶必要的 AD 設定

REST API 整合

iDempiere 透過 REST API Plugin 提供了 RESTful 介面，讓外部系統可以：

查詢和操作 iDempiere 的資料
建立文件（訂單、發票等）
執行 Process
搭配現代前端框架（React、Vue 等）建立自訂 UI

安裝方法可參考〈部署上線版的流程方法〉中的「安裝 REST API 外掛」章節。

Plugin 開發最佳實踐

優先使用 Model Validator：大部分的商業邏輯擴充都可以透過 Model Validator 實現
避免直接操作資料庫：盡量使用 iDempiere 的 Model API，而非直接寫 SQL
善用 Application Dictionary：新增欄位、視窗等盡量透過 AD 設定，減少寫程式碼
版本控制：Plugin 專案務必使用 Git 做版本管理
測試：在 GardenWorld 測試環境驗證後再部署到正式環境

小結

OSGi Plugin 架構是 iDempiere 相較於前身 ADempiere 最大的技術進步。它讓客製化開發和核心升級可以並行不悖，大幅降低了長期維護的風險和成本。

Plugin 開發需要 Java 和 OSGi 的基礎知識，學習曲線不算短，但掌握之後可以在 iDempiere 平台上實現幾乎任何商業需求。

iDempiere 開源 ERP 系列文章（完整目錄）

第 1 篇：iDempiere 是什麼？從 Compiere 到社群驅動的開源 ERP 全解析
第 2 篇：iDempiere vs Odoo vs ERPNext：開源 ERP 三強怎麼選？
第 3 篇：多租戶架構解密：Client、Organization、Role 的設計哲學
第 4 篇：快速體驗：用 Docker 十分鐘跑起來
第 5 篇：正式環境部署：從零到上線的完整指南
第 6 篇：銷售流程全走查：從報價到收款
第 7 篇：採購流程全走查：從請購到付款
第 8 篇：庫存與物料管理：倉庫、定價與產品屬性設定
第 9 篇：會計與財務報表：文件驅動會計的哲學與實踐
第 10 篇：退貨處理與 Open Items 管理
第 11 篇：製造模組入門：BOM、工單與生產排程
第 12 篇：Workflow 引擎與商業流程自動化
第 13 篇：Plugin 開發入門：用 OSGi 擴充 iDempiere（本篇）
第 14 篇：台灣在地化挑戰：統一發票、會計法規與中文化
第 15 篇：導入實戰建議：從評估、規劃到上線的路線圖

參考資料

取消回覆

文章

文章