Understanding MyBatis Plugins: Mechanisms, Use Cases, and Design Patterns

What Is a MyBatis Plugin

MyBatis plugins, more accurately called interceptors, use the proxy pattern to intercept method calls on core MyBatis components (Executor, ParameterHandler, ResultSetHandler, StatementHandler) and allow custom logic such as SQL logging, permission control, and pagination.

Typical Use Cases

Pagination: Replace default in‑memory pagination by intercepting StatementHandler.prepare and modifying the SQL to a paged version.

Unified Assignment of Common Fields: Intercept Executor.update to automatically set creator, create‑time, modifier, and modify‑time fields.

Performance Monitoring: Intercept Executor.update, Executor.query, etc., and log execution time.

Supported Interceptable Methods

Executor (update, query, commit, rollback, …)

ParameterHandler (getParameterObject, setParameters)

ResultSetHandler (handleResultSets, handleOutputParameters)

StatementHandler (prepare, parameterize, batch, update, query)

Interception Stages

The MyBatis execution flow (reading XML config, building SqlSessionFactory, opening SqlSession, executing statements, and closing) is illustrated with a sequence diagram; the plugin intercepts the four core classes at the points shown in red.

Plugin Configuration Loading

MyBatis reads plugin definitions from the XML configuration, creates an Interceptor instance for each class, calls setProperties, and adds the interceptor to the Configuration.interceptorChain.

Dynamic Proxy Generation

All interceptable objects are wrapped by InterceptorChain.pluginAll, which iterates over the interceptor list, invoking each interceptor’s plugin method to produce a proxy via Proxy.newProxyInstance. Multiple interceptors result in a nested proxy chain.

Execution of Intercept Logic

When a proxied method is called, MyBatis’s Plugin.invoke checks whether the method belongs to an intercepted class, retrieves the corresponding Invocation object, and either runs the custom intercept logic or proceeds to the original method via invocation.proceed().

Typical Interceptor Implementation

intercept: Obtain the target object and method arguments from Invocation, apply custom logic (e.g., modify SQL for pagination), then call invocation.proceed().

plugin: Return a proxy that delegates to the interceptor.

setProperties: Initialize interceptor configuration.

Design Patterns and Software Principles

Design Patterns: Proxy pattern, Chain of Responsibility.

Software Thought: Aspect‑Oriented Programming (AOP) to reduce coupling between modules.

Best Practices and Caveats

Avoid excessive plugins to prevent deep proxy nesting and performance degradation.

Never omit invocation.proceed() in intercept, otherwise the interceptor chain will break.