Apache Wayang 常用 CLI 命令与工具详解

汇总 Apache Wayang 1.1.1 命令行工具：实测 Maven 构建与依赖分析、java 直跑与堆参数、jar javap jps 用法，以及 wayang-profiler 算子剖析工具的调用与可用算子清单。

Apache WayangApache Wayang2026/10/12

Apache Wayang 常用 CLI 命令与工具详解

一、工具总览

Apache Wayang 是嵌入式 Java 库，不提供独立的主服务进程与专属 shell 脚本，日常操作围绕以下命令行工具展开（均在 Ubuntu 22.04 + OpenJDK 17.0.20.1 + Maven 3.6.3 + Wayang 1.1.1 环境实测）：

工具用途
mvn工程构建、依赖管理、依赖树分析
java直接运行 Wayang 任务
jar / javap / jpsJDK 自带：查看 jar 内容、反编译看 API 签名、验证运行中 JVM
wayang-profiler官方性能剖析工具，测量算子吞吐与耗时

本文命令默认在工程目录 /root/wayang-demo 下执行，工程与依赖结构同《Ubuntu 22.04 安装 Apache Wayang 指南》。

二、Maven 命令详解

2.1 环境确认

mvn -version

实测回显：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

Wayang 1.x 必须确认 Java version 为 17.x，否则后续编译必然失败。

2.2 编译打包

export MAVEN_OPTS="-Xms256m -Xmx512m"
mvn clean package

实测回显（节选）：

[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ wayang-demo ---
[INFO] Building jar: /root/wayang-demo/target/wayang-demo-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

2.3 导出依赖到目录

mvn dependency:copy-dependencies -DoutputDirectory=target/lib

实测结果：409 个依赖 jar 复制到 target/lib，供 java -cp 通配符方式运行。注意该命令不清空目录中已有的旧 jar，依赖变更后建议先 rm -rf target/lib 再执行（实测踩坑：残留旧 hadoop 包曾干扰冲突排查）。

2.4 依赖树分析（排查冲突必备）

mvn dependency:tree -Dincludes=org.apache.hadoop

实测回显（节选，引入 wayang-spark 后）：

[INFO] \- org.apache.wayang:wayang-spark:jar:1.1.1:compile
[INFO]    +- org.apache.hadoop:hadoop-client:jar:3.3.6:compile
[INFO]    |  +- org.apache.hadoop:hadoop-common:jar:3.3.6:compile
[INFO]    |  +- org.apache.hadoop:hadoop-hdfs-client:jar:3.3.6:compile
[INFO]    |  +- org.apache.hadoop:hadoop-yarn-api:jar:3.3.6:compile

配合 -Dincludes=<groupId>:<artifactId> 过滤可快速定位冲突来源；排除冲突用 pom 的 <exclusions>。

2.5 手动拉取单个构件

mvn dependency:get -Dartifact=org.apache.wayang:wayang-profiler:1.1.1

实测结果：构件与 POM 下载至 /root/.m2/repository/org/apache/wayang/wayang-profiler/1.1.1/，无需修改工程 pom。

2.6 常用参数速查

参数作用实测示例
-q静默模式，仅输出错误与必要信息mvn -q package
-DoutputDirectorycopy-dependencies 目标目录-DoutputDirectory=target/lib
-Dincludesdependency:tree 过滤-Dincludes=org.apache.hadoop
-Dartifactdependency:get 指定构件-Dartifact=org.apache.wayang:wayang-profiler:1.1.1
-Dmaven.repo.local指定本地仓库位置-Dmaven.repo.local=/data/m2repo

三、java 直跑 Wayang 任务

3.1 标准 classpath 运行

java -Xms256m -Xmx512m -cp "target/wayang-demo-1.0.0.jar:target/lib/*" com.example.WordCount

实测回显：

big: 2
a: 1
data: 3
streams: 1
cross: 1
run: 1
is: 1
wayang: 4
backends: 1
processor: 1
platform: 1
with: 1
can: 1
java: 2
apache: 2
spark: 2
and: 2
mixes: 1
on: 1

要点：-cp 通配符 lib/* 必须加引号防 shell 展开；堆参数 256-512 MB 直接跟在 java 命令后。

3.2 Spark 后端的 add-opens 参数

用 wayang-spark 后端在 Java 17 上运行时，必须为 JVM 追加模块开放参数，否则实测报 IllegalAccessError ... cannot access class sun.nio.ch.DirectBuffer。完整可用命令（实测跑通）：

java -Xms256m -Xmx512m \
  --add-opens java.base/java.lang=ALL-UNNAMED \
  --add-opens java.base/java.lang.invoke=ALL-UNNAMED \
  --add-opens java.base/java.lang.reflect=ALL-UNNAMED \
  --add-opens java.base/java.io=ALL-UNNAMED \
  --add-opens java.base/java.net=ALL-UNNAMED \
  --add-opens java.base/java.nio=ALL-UNNAMED \
  --add-opens java.base/java.util=ALL-UNNAMED \
  --add-opens java.base/java.util.concurrent=ALL-UNNAMED \
  --add-opens java.base/java.util.concurrent.atomic=ALL-UNNAMED \
  --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
  --add-opens java.base/sun.util.calendar=ALL-UNNAMED \
  --add-opens java.security.jgss/sun.security.krb5=ALL-UNNAMED \
  -cp "target/wayang-spark-demo-1.0.0.jar:target/lib/*" com.example.WordCountSpark

实测回显（节选）：

SPARK>> can: 1
SPARK>> big: 2
SPARK>> cross: 1
SPARK>> spark: 2

四、JDK 自带工具

4.1 jar：查看构件内容

jar tf /root/.m2/repository/org/apache/wayang/wayang-core/1.1.1/wayang-core-1.1.1.jar | grep -E "\.properties$"

实测回显：

wayang-core-defaults.properties
META-INF/maven/org.apache.wayang/wayang-core/pom.properties

提取内置默认配置文件（结合《Apache Wayang 配置参数详解》使用）：

cd /tmp && jar xf /root/.m2/repository/org/apache/wayang/wayang-core/1.1.1/wayang-core-1.1.1.jar wayang-core-defaults.properties

4.2 javap：核实 API 签名

Wayang 版本间 API 变动频繁（如 withUdfJars 更名 withUdfJarOf），编码前先核实：

javap -cp "target/wayang-demo-1.0.0.jar:target/lib/*" org.apache.wayang.core.api.Configuration | grep -iE "setProperty|getStringProperty"

实测回显：

  public void setProperty(java.lang.String, java.lang.String);
  public java.lang.String getStringProperty(java.lang.String);
  public java.lang.String getStringProperty(java.lang.String, java.lang.String);
  public java.util.Optional<java.lang.String> getOptionalStringProperty(java.lang.String);

4.3 jps：验证运行中的 JVM 与参数

任务运行期间执行：

jps -v

实测回显：

5820 WordCount -Xms256m -Xmx512m

配合 ps -ef | grep "[j]ava -Xms"（实测回显 java -Xms256m -Xmx512m -cp target/wayang-demo-1.0.0.jar:target/lib/* com.example.WordCount）双重确认堆参数生效。

五、wayang-profiler 性能剖析工具

5.1 获取与定位

profiler 是 Wayang 官方发布的算子剖析工具（独立构件，不在 wayang-core 内）：

mvn dependency:get -Dartifact=org.apache.wayang:wayang-profiler:1.1.1
jar tf /root/.m2/repository/org/apache/wayang/wayang-profiler/1.1.1/wayang-profiler-1.1.1.jar | grep "class$" | grep -v '\$' | head

实测回显（节选）：

org/apache/wayang/profiler/data/DataGenerators.class
org/apache/wayang/profiler/hardware/DiskProfiler.class
org/apache/wayang/profiler/java/BinaryOperatorProfiler.class
org/apache/wayang/profiler/java/JavaCollectionSourceProfiler.class
org/apache/wayang/profiler/java/JavaTextFileSourceProfiler.class
org/apache/wayang/profiler/java/OperatorProfiler.class
org/apache/wayang/profiler/java/Profiler.class

主类为 org.apache.wayang.profiler.java.Profiler。

5.2 运行与用法

java -cp "/root/.m2/repository/org/apache/wayang/wayang-profiler/1.1.1/wayang-profiler-1.1.1.jar:target/lib/*" org.apache.wayang.profiler.java.Profiler

实测回显（Usage）：

Usage: java class org.apache.wayang.profiler.java.Profiler <operator to profile> <cardinality>[,<cardinality>]

两个参数：要剖析的算子名（小写形式）与数据量基数（可多级逗号分隔）。

5.3 实测剖析 map 算子

java -Xms256m -Xmx512m -cp "/root/.m2/repository/org/apache/wayang/wayang-profiler/1.1.1/wayang-profiler-1.1.1.jar:target/lib/*" org.apache.wayang.profiler.java.Profiler map 1000

实测回显：

Running garbage collector...
Sleeping for 0:00:01.000.
Profiling org.apache.wayang.profiler.java.UnaryOperatorProfiler@2e32ccc5 with 1000 data quanta.
Prepare...
Execute...
Sleeping for 0:00:01.000.

工具完成 GC 预热、间隔采样、执行测量后输出剖析结果，退出码 0。传入不存在的算子名实测返回 Unknown operator: JavaMapOperator——算子名必须用小写短名而非类名。

5.4 可用算子名清单（实测提取）

从 Profiler 类字节码常量提取的合法算子名（小写）：

callbacksink, cartesian, collectionsource, count, distinct, filter, flatmap, globalreduce,
map, reduceby, textfilesource, sort, join, cogroup, intersect, union, ...

其中 map、filter、flatmap、reduceby、textfilesource、collectionsource 已实测可被识别（map 1000 全流程跑通）。

六、常见问题

Q1：mvn package 提示 invalid target release: 17？ Maven 跑在 17 以下的 JDK 上。用 mvn -version 核对 Java version 行，切换 JAVA_HOME 到 JDK 17 后重试（实测切换后编译通过）。

Q2：java -cp 运行报 ClassNotFoundException 或 NoClassDefFoundError？ 检查三点：classpath 引号是否包裹（"target/lib/*"）；target/lib 是否已生成（先跑 mvn dependency:copy-dependencies）；主类全名是否正确。实测标准命令见 3.1 节。

**Q3：**profiler 报 Unknown operator: <名称>？ 算子名要用小写短名（如 map），不能用 Java 类名（如 JavaMapOperator），实测二者行为不同；完整清单见 5.4 节。

Q4：jps -v 看不到目标进程？ 任务执行过快（小数据量下 WordCount 数秒完成）会错过观测窗口。可临时加大输入数据，或后台启动后立即执行 jps -v（实测 sleep 1 秒内可捕获）。

七、参考链接

  1. Apache Wayang 官网：https://wayang.apache.org/
  2. 快速上手指南：https://wayang.apache.org/docs/guide/getting-started
  3. GitHub 仓库（apache/wayang，Profiler 源码所在）：https://github.com/apache/wayang
  4. Maven Central 上 wayang-profiler 构件：https://repo1.maven.org/maven2/org/apache/wayang/wayang-profiler/
  5. Maven Central 上 wayang-core 构件：https://repo1.maven.org/maven2/org/apache/wayang/wayang-core/
  6. Sonatype Central（版本检索）：https://central.sonatype.com/artifact/org.apache.wayang/wayang-core