MyBatis Entity Class Basic Guidelines

In the MyBatis framework, Java entity classes (POJOs) serve as the core bridge connecting the Java object model to database table structures. By utilizing reflection mechanisms, MyBatis automatically maps column names in SQL statements to entity class properties. Therefore, adhering to strict naming conventions is crucial for code maintainability, performance optimization, and the accuracy of type conversion. A well-designed entity class not only reduces redundancy in XML mapping files or annotation configurations but also effectively prevents serialization exceptions caused by missing TypeHandler implementations.
MyBatis adopts "CamelCase" as the standard naming style for Java properties by default. This practice ensures code conciseness and consistency while aligning with common habits in the mainstream development community. When entity class properties follow this convention, MyBatis can automatically identify and handle field mapping logic without requiring additional complex resultMap configurations or custom processors.

  1. Lowercase First Letter Rule: The first character of all Java Bean properties must be a lowercase letter (e.g., userName, createTime).
  2. Word Separation: Multiple English words are connected using underscores _, with each new word starting with an uppercase letter (e.g., user_name is incorrect; it should be userName; and User_Name is also incorrect because the first letter should not be uppercase).
  3. Avoid Special Naming Conflicts: Do not name properties as reserved words or constants identical to MyBatis internal constants, as this may lead to reflection retrieval failures.

Mapping Mechanism Between SQL Column Names and Java Properties

When processing resultMap, MyBatis defaults to converting database field names (typically following the underscore-separated style) into lowercase first-letter forms of CamelCase property names within entity classes for matching. This conversion process relies on MyBatis's automatic type converter logic. If the SQL query returns column names such as user_name and create_time, while the Java code defines properties as userName and createTime, MyBatis will automatically complete the mapping from underscore-separated to CamelCase.

However, if there is an inconsistency between entity class property naming rules and database field name conversion rules, or if special data types (such as dates or JSON) are involved, explicit mapping configuration is required. In such cases, it is recommended to use the <resultMap> tag to explicitly specify the correspondence between column names and properties:

<resultMap id="UserResultMap" type="com.example.User">
    <id column="user_id" property="userId"/> <!-- Primary key field -->
    <result column="create_time" property="createTime"/>
</resultMap>

Best Practices to Avoid Type Conversion Errors

In practical development, the most common issue regarding entity class specifications is not incorrect naming formats but rather TypeHandler missing due to data type mismatches. For instance, date columns in databases are typically stored as strings or long integers (milliseconds), whereas Java objects expect standard java.util.Date or LocalDateTime types.

If the corresponding <typeHandler> element is not configured in the XML mapping file, MyBatis will fail to correctly parse the data stream, resulting in a conversion exception. Therefore, entity class design should consider the generality of property types:

  • Date/Time Fields: It is recommended to use java.util.Date, LocalDateTime, or Instant directly and configure appropriate handlers (such as org.apache.ibatis.type.AliasTypeHandler) in the mapping file.
  • Boolean Fields: If the database uses TINYINT(1) to store boolean logic, entity class properties should be defined as the Boolean type rather than simple boolean, to support flexible conversion during JSON serialization.

Summary and Checklist

To ensure that entity classes in MyBatis projects adhere to core development specifications, it is recommended to follow these inspection steps when writing code:

  • Verify whether all Java Bean properties strictly follow CamelCase naming (lowercase first letter + underscore separation).
  • Validate whether the mapping logic between database field names and Java properties is correct.
  • Explicitly configure typeHandler within <resultMap> for complex types such as dates and timestamps.
  • Check if entity classes use correct generic wrappers (e.g., List<User>, Set<String>), to support automatic mapping of collection types.

Adhering to these specifications not only enhances code readability but also significantly reduces the risk of online failures caused by data parsing errors, serving as a fundamental requirement for building high-availability MyBatis applications.