Apache Aries 快速入门与集成示例
Apache Aries 快速入门与集成示例：从环境准备与启动运行时，到编写提供方与消费方两个 Blueprint bundle、构建部署并验证服务装配闭环，再到 Karaf、Equinox 集成方式说明。
Apache AriesAries2026/10/14
Apache Aries 快速入门与集成示例
目标：以 Aries Blueprint 1.10.3 + Felix 7.0.5 为例，从零跑通「编写服务接口 → Blueprint XML 装配 → 构建 bundle → 部署运行 → 跨 bundle 服务调用」全链路，并给出与其他 OSGi 运行时集成的方式说明。
一、快速入门
1.1 环境准备
| 项目 | 要求 |
|---|---|
| JDK | 17（示例 bundle 声明 osgi.ee=JavaSE 17） |
| Maven | 3.6.3 及以上（CentOS 8 需 3.9.9） |
| Felix | 7.0.5（org.apache.felix.main-7.0.5.jar） |
| Aries 组件 | org.apache.aries.blueprint.core 1.10.3 及依赖 |
| 运行账号 | root |
1.2 启动运行时并观察组件
cd /opt/felix
java -jar bin/felix.jar
真实回显：
[Blueprint Extender: 1] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle org.apache.aries.blueprint.core/1.10.3 has been started
Welcome to Apache Felix Gogo
g!
进入 Gogo shell 后执行 lb：
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (7.0.5)|7.0.5
1|Active | 1|org.objectweb.asm (9.6.0)|9.6.0
2|Active | 1|file:/opt/felix/bundle/blueprint-parser-1.6.0.jar (0.0.0)|0.0.0
3|Active | 1|jansi (1.18.0)|1.18.0
4|Active | 1|JLine Bundle (3.13.2)|3.13.2
5|Active | 1|Apache Aries Blueprint API (1.0.1)|1.0.1
6|Active | 1|Apache Aries Blueprint Core (1.10.3)|1.10.3
7|Active | 1|Apache Aries Proxy API (1.1.1)|1.1.1
8|Active | 1|Apache Aries Proxy Service (1.0.6)|1.0.6
9|Active | 1|Apache Aries Quiesce API (1.0.0)|1.0.0
10|Active | 1|Apache Aries Util (1.1.3)|1.1.3
11|Active | 1|Apache Felix Bundle Repository (2.0.10)|2.0.10
12|Active | 1|Apache Felix Gogo Command (1.1.2)|1.1.2
13|Active | 1|Apache Felix Gogo JLine Shell (1.1.8)|1.1.8
14|Active | 1|Apache Felix Gogo Runtime (1.1.4)|1.1.4
15|Active | 1|slf4j-api (1.7.36)|1.7.36
16|Active | 1|slf4j-simple (1.7.36)|1.7.36
解读：ID 0 为 System Bundle（框架自身），ID 1–16 为 Aries Blueprint 及其依赖组件，全部 Active。
💡 技术拓展：同样的 Aries Blueprint 组件可以部署到不同 OSGi 运行时——Apache Felix 轻量直接；Apache Karaf 提供特性（feature）安装机制，一条命令即可安装 aries-blueprint 特性；Eclipse Equinox 则常用于 Eclipse RCP 集成场景。三者运行时行为一致，部署载体不同。
二、编写提供方 bundle
2.1 工程结构
demo/
├── pom.xml
└── src/main/
├── java/com/example/aries/api/Greeting.java
├── java/com/example/aries/impl/GreetingImpl.java
└── resources/OSGI-INF/blueprint/demo.xml
2.2 服务接口与实现
package com.example.aries.api;
public interface Greeting {
String greet(String name);
}
package com.example.aries.impl;
import com.example.aries.api.Greeting;
public class GreetingImpl implements Greeting {
private String prefix = "Hello";
public void setPrefix(String prefix) {
this.prefix = prefix;
}
@Override
public String greet(String name) {
return prefix + ", " + name + "!";
}
}
2.3 Blueprint 装配描述 demo.xml
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
<bean id="greetingBean" class="com.example.aries.impl.GreetingImpl">
<property name="prefix" value="Hello"/>
</bean>
<service ref="greetingBean" interface="com.example.aries.api.Greeting"/>
</blueprint>
装配语义：bean 声明实例与属性注入；service 将 bean 注册为 OSGi 服务。
2.4 pom.xml 要点
<packaging>bundle</packaging>
<dependencies>
<dependency>
<groupId>org.osgi</groupId>
<artifactId>org.osgi.service.blueprint</artifactId>
<version>1.0.2</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>5.1.9</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-SymbolicName>com.example.aries.blueprint.demo</Bundle-SymbolicName>
<Bundle-Version>1.0.0</Bundle-Version>
<Export-Package>com.example.aries.api,com.example.aries.impl</Export-Package>
</instructions>
</configuration>
</plugin>
</plugins>
</build>
packaging=bundle 配合 maven-bundle-plugin 才会生成 OSGi 响应头。
三、编写消费方 bundle
3.1 工程结构
consumer/
├── pom.xml
└── src/main/
├── java/com/example/aries/consumer/GreetingClient.java
└── resources/OSGI-INF/blueprint/consumer.xml
3.2 客户端类
package com.example.aries.consumer;
import com.example.aries.api.Greeting;
public class GreetingClient {
private Greeting greeting;
public void setGreeting(Greeting greeting) {
this.greeting = greeting;
}
public void init() {
System.out.println("[consumer] " + greeting.greet("Aries Blueprint"));
}
}
3.3 装配描述 consumer.xml
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
<reference id="greetingRef" interface="com.example.aries.api.Greeting"/>
<bean id="client" class="com.example.aries.consumer.GreetingClient"
init-method="init">
<property name="greeting" ref="greetingRef"/>
</bean>
</blueprint>
装配语义：reference 声明对 Greeting 服务的依赖；bean 在依赖满足后创建，init-method 触发业务调用。
四、构建与检查
4.1 构建命令
cd /opt/aries-src/demo
mvn install -DskipTests
cd /opt/aries-src/consumer
mvn package -DskipTests
4.2 产物
-rw-r--r-- 1 root root 4447 Oct 13 16:31 /opt/aries-src/demo/target/aries-blueprint-demo-1.0.0.jar
-rw-r--r-- 1 root root 4045 Oct 13 16:31 /opt/aries-src/consumer/target/aries-blueprint-consumer-1.0.0.jar
4.3 MANIFEST 检查
Bundle-SymbolicName = com.example.aries.blueprint.demo
Bundle-Blueprint = OSGI-INF/blueprint/demo.xml
Export-Service = com.example.aries.api.Greeting;osgi.service.blueprint.compname=greetingBean
Require-Capability = osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=17))"
要点：Bundle-Blueprint 指向装配描述，是 Aries 扩展器识别装配文件的依据。
五、部署与验证
5.1 安装并启动
g! install file:/opt/aries-src/demo/target/aries-blueprint-demo-1.0.0.jar
Bundle ID: 17
g! start 17
[Blueprint Extender: 2] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle com.example.aries.blueprint.demo/1.0.0 has been started
g! install file:/opt/aries-src/consumer/target/aries-blueprint-consumer-1.0.0.jar
Bundle ID: 19
g! start 19
[consumer] Hello, Aries Blueprint!
[Blueprint Extender: 1] INFO org.apache.aries.blueprint.container.BlueprintContainerImpl - Blueprint bundle com.example.aries.blueprint.consumer/1.0.0 has been started
验证结果：提供方 Blueprint 运行时先创建并注册服务；消费方运行时随后创建，reference 命中后完成跨 bundle 服务调用。
5.2 检查服务注册表
g! inspect cap service 17
com.example.aries.blueprint.demo [17] provides:
-----------------------------------------------
service; com.example.aries.api.Greeting with properties:
osgi.service.blueprint.compname = greetingBean
service.bundleid = 17
service.id = 33
service.scope = bundle
Used by:
com.example.aries.blueprint.consumer [19]
service; org.osgi.service.blueprint.container.BlueprintContainer with properties:
osgi.blueprint.container.symbolicname = com.example.aries.blueprint.demo
osgi.blueprint.container.version = 1.0.0
service.bundleid = 17
service.id = 34
service.scope = singleton
解读：demo 提供 Greeting（被 consumer 使用）与 BlueprintContainer 两类服务，装配闭环成立。
5.3 停止与清理
g! stop 17
g! uninstall 19
[pipe-uninstall 19] INFO org.apache.aries.blueprint.container.BlueprintExtender - Destroying container for blueprint bundle com.example.aries.blueprint.consumer/1.0.0
六、与其他运行时集成
6.1 集成到 Apache Karaf
Aries Blueprint 是 Karaf 的标准组件。在 Karaf shell 中启用 blueprint 特性后，将上述两个 jar 放入 deploy/ 目录即可热部署，行为与 Felix 一致（运行时创建、服务调用、销毁日志相同），无需修改任何源码与装配文件。
6.2 集成到 Eclipse Equinox
在 Equinox 中通过配置文件（features/plugins）加入相同版本的 Aries 组件与示例 bundle，Aries 扩展器同样会为每个含装配描述的 bundle 创建运行时，服务调用方式不变。
6.3 集成要点总结
| 运行时 | 部署方式 | 差异点 |
|---|---|---|
| Apache Felix | bundle/ 自动部署或 gogo install | 最轻量，适合学习调试 |
| Apache Karaf | 特性安装或 deploy/ 热部署 | 提供远程 shell、特性管理与日志整合 |
| Eclipse Equinox | 配置文件静态装配 | 与 Eclipse RCP 生态集成 |
Aries 组件本身与运行时无关，迁移只需更换宿主与部署方式。
七、参考链接
- Apache Aries 官方网站：https://aries.apache.org/
- Aries Blueprint 模块说明：https://aries.apache.org/modules/blueprint.html
- OSGi Blueprint 服务规范：https://osgi.org/specification/osgi.enterprise/7.0.0/service.blueprint.html
- Apache Felix 官方网站：https://felix.apache.org/
- Apache Karaf 官方网站：https://karaf.apache.org/
章节目录