SQL Coloring Plugin for MyBatis: Design, Implementation, and Usage Guide

Backend developers often struggle to quickly locate the business origin of a SQL statement in large, complex systems, especially when dealing with numerous dynamically generated queries.

Inspired by name‑tags on staff uniforms, the author designed a MyBatis plugin that "colors" SQL statements by inserting comment‑based markers. The plugin is lightweight, requires no changes to business code or existing SQL, and supports SELECT, INSERT, UPDATE, DELETE, as well as statements without a WHERE clause.

The core implementation intercepts the StatementHandler in MyBatis, appending a comment that contains the statementId (mapper namespace + SQL id), a generated pFinderId , and any additional context supplied via a ThreadLocal . Example of the generated comment:

/* [SQLMarking] statementId: com.example.dao.UserDao.selectUser, pFinderId: 4630283.56667.17392048399060130, operator: john_doe, traceId: abc123 */

Usage steps include adding the Maven dependency, configuring the interceptor in mybatis-config.xml , and optionally setting custom fields with SQLMarkingThreadLocal.put(key, value) before executing SQL.

<dependency>
    <groupId>com.jd.sword</groupId>
    <artifactId>sword-mybatis-plugins</artifactId>
    <version>1.0.2-SNAPSHOT</version>
</dependency>

<plugin interceptor="com.jd.sword.mybatis.plugin.sql.SQLMarkingInterceptor">
    <property name="enabled" value="true"/>
</plugin>

SQLMarkingThreadLocal.put("operator", UserInfoUtil.getUserCode());
// execute SQL
SQLMarkingThreadLocal.remove();

Performance tests show the additional overhead is typically 0–1 ms per SQL, rarely exceeding 3–4 ms, which does not affect overall response time. The plugin currently supports MyBatis (including MyBatis‑Plus) but does not work with raw JDBC, JdbcTemplate, or other ORM frameworks.

The article also provides a FAQ covering MyBatis‑Plus compatibility, plugin ordering, and common error resolutions, guiding readers on how to adopt the plugin in test, UAT, and production environments.