Skip to main content
Version: 0.4.0



This document explains how to install apisix-java-plugin-runner.


  • JDK 11
  • APISIX master branch
  • Refer to Debug to build the debug environment.


  1. Create a simple web application with Spring Boot, and choose Maven as the build tool.

  2. Add the apisix-java-plugin-runner dependency in your POM, like:

  1. Configuring the scan package path

@SpringBootApplication(scanBasePackages = {"your-filter's-package-name","org.apache.apisix.plugin.runner"})
  1. Excluding the default logging framework

To prevent multiple slf4j bindings, exclude the logback-classic and log4j-to-slf4j in pom.xml, like:

  1. Configuring the address for Unix Domain Socket communication with APISIX
socket.file = /tmp/runner.sock
  1. Implementing the PluginFilter interface

When you write your custom plugins, you need to implement the PluginFilter interface and inject filters into Spring Boot's object lifecycle management using @Component.

code example:

public class RewriteRequestDemoFilter implements PluginFilter {
implementing functions

You can refer to development to learn how to write custom plugins.


A Demo Project that work with apisix-java-plugin-runner and custom filters can be found at: java-plugin-runner-demo.