How MyBatis Plugins Execute: Core Interface and Runtime Flow

MyBatis is a widely used Java persistence framework that offers a flexible plugin mechanism, allowing developers to intercept and modify SQL statements, parameters, and results for purposes such as performance monitoring, logging, and permission control.

The core of the plugin system is the Interceptor interface, which defines three methods: Object intercept(Invocation invocation): intercepts the target method execution; the Invocation object contains the method call information and allows modification of arguments or return values. Object plugin(Object target): wraps the target object (e.g., Executor, StatementHandler) with a proxy via Plugin.wrap. void setProperties(Properties properties): receives configuration properties for the plugin.

When MyBatis performs an operation such as a query, insert, or update, it builds an interceptor chain. It looks up plugins defined in the configuration and applies them to core components like Executor, StatementHandler, ParameterHandler, and ResultSetHandler. Each plugin wraps these objects, intercepting method calls before and after execution.

To create a plugin, implement the Interceptor interface, use Plugin.wrap in the plugin method to create a proxy, and place the custom logic in the intercept method. The example below shows a simple logging plugin that prints the SQL statement before execution.

package com.example.mybatis.plugin;

import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.plugin.Interceptor;
import org.apache.ibatis.plugin.Invocation;
import org.apache.ibatis.plugin.Plugin;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.session.RowBounds;
import java.util.Properties;

public class MyBatisLoggingPlugin implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // Get the target method (the SQL to be executed)
        Object target = invocation.getTarget();
        // Only handle Executor methods
        if (target instanceof Executor) {
            MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
            Object parameter = invocation.getArgs()[1];
            // Log the SQL before execution
            System.out.println("Executing SQL: " + ms.getSqlSource().getBoundSql(parameter).getSql());
        }
        // Proceed with the original method
        return invocation.proceed();
    }

    @Override
    public Object plugin(Object target) {
        // Wrap the target with a proxy if it is an Executor
        if (target instanceof Executor) {
            return Plugin.wrap(target, this);
        }
        return target;
    }

    @Override
    public void setProperties(Properties properties) {
        // Read plugin configuration if needed
    }
}

The plugin is registered in the MyBatis configuration file as follows:

<plugins>
    <plugin interceptor="com.example.mybatis.plugin.MyBatisLoggingPlugin"/>
</plugins>

Runtime flow:

Interceptor chain : MyBatis scans the configuration for plugins and applies them to target objects such as Executor.

Plugin wrapping : Plugin.wrap creates a proxy for the target object, ensuring all SQL operations pass through the interceptor.

Intercept method : The intercept method can process the SQL (e.g., logging) and then calls invocation.proceed() to continue execution.

Post‑execution handling : After the original method returns, the interceptor can further process the result (e.g., caching, additional logging).

In summary, MyBatis plugins provide powerful extensibility by implementing the Interceptor interface. Through proxy‑based wrapping, developers can easily add features such as performance monitoring, SQL logging, and permission verification without modifying the core framework.