Deep Dive into MyBatis SQL Execution Process and Custom TypeHandler

MyBatis is a widely used persistence framework, but many developers are unclear about its internal SQL execution workflow. This article walks through the complete process, starting from obtaining a SqlSession and a mapper interface, to the intricate steps of binding mapper interfaces with XML mapping files.

Mapper Retrieval (getMapper) : When session.getMapper(UserMapper.class) is called, MyBatis looks up the mapper in the Configuration object's MapperRegistry , creates a dynamic proxy (MapperProxy) via JDK proxy, and stores the proxy in the knownMappers map.

Binding Mapper and XML : During SqlSessionFactoryBuilder.build() , the XML configuration is parsed, loading each mapper interface and its corresponding XML file. The MapperRegistry registers the mapper, and the Configuration adds it to mappedStatements , linking the interface method to the SQL statement defined in the XML.

SQL Execution Flow : The proxy’s invoke method creates a MapperMethod that encapsulates the method’s metadata and the associated SQL. Execution then proceeds to Executor.execute , which selects the appropriate StatementHandler (e.g., PreparedStatementHandler ) and calls prepare , parameterize , and finally query to run the statement against the database.

Parameter Mapping : MyBatis uses TypeHandler implementations to set JDBC parameters. Default handlers (e.g., StringTypeHandler , IntegerTypeHandler ) are automatically chosen based on Java type, but developers can specify a custom handler with typeHandler=com.example.MyTypeHandler . The article provides a full example of a custom MyTypeHandler that logs when parameters are set.

Result Set Mapping : After query execution, ResultSetHandler.handleResultSets processes the JDBC ResultSet . It also relies on TypeHandler to convert column values to Java objects. The article shows how to override getNullableResult methods in a custom handler to control result conversion.

Custom TypeHandler Example : The author presents a complete Java class implementing BaseTypeHandler with overridden setNonNullParameter , getNullableResult (by column name, index, and callable statement). The mapper XML is updated to use this handler for both input parameters and result columns.

Summary : By understanding the mapper‑XML binding, the proxy‑based execution path, and the role of TypeHandler , developers can debug MyBatis more effectively and extend its behavior for special data types or custom conversion logic.