graph TD
    A[Java Application] -->|调用| B[Mapper Interface]
    B -->|代理实现| C[MyBatis Core]
    C -->|解析| D[XML/Annotation SQL]
    C -->|执行| E[JDBC]
    E -->|连接| F[Database]

<!-- UserMapper.xml -->
<select id="selectUserById" resultType="com.example.User">
    SELECT id, name, email, create_time 
    FROM users 
    WHERE id = #{id}
    AND is_deleted = 0
</select>

// Mapper接口
public interface UserMapper {
    User selectUserById(Long id);
    
    @Select("SELECT * FROM users WHERE name LIKE CONCAT('%',#{name},'%')")
    List<User> searchUsersByName(@Param("name") String name);
}

graph TD
    A[MyBatis Core] --> B[MyBatis Plus Core]
    B --> C[通用Mapper]
    B --> D[通用Service]
    B --> E[条件构造器]
    B --> F[插件体系]
    F --> G[分页插件]
    F --> H[性能分析插件]
    F --> I[乐观锁插件]
    F --> J[防止全表更新插件]

// 实体类
@Data
@TableName("users")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;
    private String email;
    @TableField(fill = FieldFill.INSERT)
    private Date createTime;
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date updateTime;
    @TableLogic
    private Integer isDeleted;
}

// Mapper接口 - 无需编写SQL
public interface UserMapper extends BaseMapper<User> {}

// 服务层调用
@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    
    // 通用查询
    public List<User> getUsersByAge(Integer minAge, Integer maxAge) {
        return userMapper.selectList(
            new LambdaQueryWrapper<User>()
                .ge(User::getAge, minAge)
                .le(User::getAge, maxAge)
                .orderByDesc(User::getCreateTime)
        );
    }
    
    // 分页查询
    public Page<User> pageUsers(int pageNum, int pageSize) {
        Page<User> page = new Page<>(pageNum, pageSize);
        return userMapper.selectPage(page, 
            new LambdaQueryWrapper<User>().orderByDesc(User::getCreateTime));
    }
}

graph LR
    A[MyBatis Core] --> B[tk-mybatis Core]
    B --> C[Mapper<T> Interface]
    B --> D[Example 类]
    B --> E[MySqlMapper etc.]
    B --> F[代码生成器]

// 实体类（无注解示例）
public class User {
    private Long id;
    private String name;
    private String email;
    private Date createTime;
    // getters/setters
}

// Mapper接口
public interface UserMapper extends Mapper<User> {
    // 可以继续定义自己的方法
    @Select("SELECT * FROM users WHERE name LIKE CONCAT('%',#{name},'%')")
    List<User> searchByName(String name);
}

// 服务层调用
@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    
    // 通用查询
    public List<User> getUsersByAge(Integer minAge, Integer maxAge) {
        Example example = new Example(User.class);
        example.createCriteria()
            .andGreaterThan("age", minAge)
            .andLessThanOrEqualTo("age", maxAge);
        example.orderBy("createTime").desc();
        
        return userMapper.selectByExample(example);
    }
    
    // 分页需要配合PageHelper
    public PageInfo<User> pageUsers(int pageNum, int pageSize) {
        PageHelper.startPage(pageNum, pageSize);
        List<User> users = userMapper.selectAll();
        return new PageInfo<>(users);
    }
}

// 需要高度定制化SQL，考虑性能和事务
@Repository
public class TransactionMapper {
    @Select({
        "<script>",
        "SELECT t.*, a.balance as account_balance",
        "FROM transactions t",
        "JOIN accounts a ON t.account_id = a.id",
        "WHERE t.create_time BETWEEN #{startTime} AND #{endTime}",
        "<if test='accountId != null'>",
        "  AND t.account_id = #{accountId}",
        "</if>",
        "<if test='minAmount != null'>",
        "  AND t.amount >= #{minAmount}",
        "</if>",
        "ORDER BY t.create_time DESC",
        "LIMIT #{offset}, #{limit}",
        "</script>"
    })
    @Results(id = "transactionResult", value = {
        @Result(property = "id", column = "id"),
        @Result(property = "amount", column = "amount", typeHandler = MoneyTypeHandler.class),
        @Result(property = "account", column = "account_id", 
                one = @One(select = "com.example.mapper.AccountMapper.selectById"))
    })
    List<Transaction> findComplexTransactions(
        @Param("startTime") Date startTime,
        @Param("endTime") Date endTime,
        @Param("accountId") Long accountId,
        @Param("minAmount") BigDecimal minAmount,
        @Param("offset") int offset,
        @Param("limit") int limit
    );
}

@Data
@TableName("products")
public class Product {
    @TableId(type = IdType.ASSIGN_ID) // 雪花ID
    private Long id;
    private String name;
    private String description;
    private BigDecimal price;
    private Integer stock;
    private String category;
    private String imageUrl;
    
    @TableField(fill = FieldFill.INSERT)
    private Date createTime;
    
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date updateTime;
    
    @TableLogic
    private Integer isDeleted;
    
    // 冗余字段 - 避免关联查询
    @TableField(exist = false)
    private List<ProductImage> images;
}

@Service
@RequiredArgsConstructor
public class ProductServiceImpl extends ServiceImpl<ProductMapper, Product> 
    implements ProductService {
    
    private final ProductImageService productImageService;
    
    @Override
    @Transactional
    public boolean saveWithImages(Product product) {
        // 1. 保存商品
        boolean saved = save(product);
        if (!saved) return false;
        
        // 2. 批量保存图片
        List<ProductImage> images = product.getImages();
        if (CollectionUtils.isNotEmpty(images)) {
            images.forEach(img -> img.setProductId(product.getId()));
            productImageService.saveBatch(images);
        }
        
        return true;
    }
    
    @Override
    public Page<ProductVO> searchProducts(ProductQuery query) {
        // 构建条件
        LambdaQueryWrapper<Product> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(Product::getIsDeleted, 0);
        
        if (StringUtils.isNotBlank(query.getKeyword())) {
            wrapper.and(w -> w
                .like(Product::getName, query.getKeyword())
                .or()
                .like(Product::getDescription, query.getKeyword())
            );
        }
        
        if (StringUtils.isNotBlank(query.getCategory())) {
            wrapper.eq(Product::getCategory, query.getCategory());
        }
        
        if (query.getMinPrice() != null) {
            wrapper.ge(Product::getPrice, query.getMinPrice());
        }
        
        if (query.getMaxPrice() != null) {
            wrapper.le(Product::getPrice, query.getMaxPrice());
        }
        
        wrapper.orderByDesc(Product::getCreateTime);
        
        // 分页查询
        Page<Product> page = new Page<>(query.getPageNum(), query.getPageSize());
        Page<Product> productPage = page(page, wrapper);
        
        // 转换为VO，补充图片等信息
        return productPage.convert(product -> {
            ProductVO vo = ProductVO.fromEntity(product);
            vo.setImages(productImageService.listByProductId(product.getId()));
            return vo;
        });
    }
    
    // 多租户查询
    @Override
    public List<Product> listByTenant(Long tenantId) {
        return list(new LambdaQueryWrapper<Product>()
            .eq(Product::getTenantId, tenantId)
            .eq(Product::getIsDeleted, 0));
    }
}

// 轻量级实体
public class Device {
    private String deviceId; // 主键
    private String name;
    private String type;
    private String status; // ONLINE/OFFLINE
    private String location;
    private Date lastActiveTime;
    private String tenantId; // 多租户
    // getters/setters
}

// 专用Mapper
public interface DeviceMapper extends Mapper<Device>, MySqlMapper<Device> {
    // 扩展方法
    @Select("SELECT * FROM devices WHERE tenant_id = #{tenantId} AND status = 'ONLINE'")
    List<Device> selectOnlineByTenant(@Param("tenantId") String tenantId);
    
    @Update("UPDATE devices SET status = 'OFFLINE' WHERE last_active_time < #{beforeTime}")
    void offlineInactiveDevices(@Param("beforeTime") Date beforeTime);
}

// 服务层
@Service
@RequiredArgsConstructor
public class DeviceService {
    
    private final DeviceMapper deviceMapper;
    private final TenantContext tenantContext;
    
    // 基础CRUD使用通用方法
    public Device getDevice(String deviceId) {
        return deviceMapper.selectByPrimaryKey(deviceId);
    }
    
    public List<Device> searchDevices(DeviceQuery query) {
        Example example = new Example(Device.class);
        Example.Criteria criteria = example.createCriteria();
        
        // 多租户隔离
        criteria.andEqualTo("tenantId", tenantContext.getCurrentTenant());
        
        if (StringUtils.isNotEmpty(query.getName())) {
            criteria.andLike("name", "%" + query.getName() + "%");
        }
        
        if (StringUtils.isNotEmpty(query.getType())) {
            criteria.andEqualTo("type", query.getType());
        }
        
        if (StringUtils.isNotEmpty(query.getStatus())) {
            criteria.andEqualTo("status", query.getStatus());
        }
        
        example.orderBy(query.getOrderBy()).orderBy(query.getSort());
        
        // 分页
        PageHelper.startPage(query.getPageNum(), query.getPageSize());
        return deviceMapper.selectByExample(example);
    }
    
    @Scheduled(fixedRate = 300000) // 5分钟
    public void checkDeviceStatus() {
        // 自动下线长时间无活动的设备
        Date offlineThreshold = new Date(System.currentTimeMillis() - 10 * 60 * 1000); // 10分钟
        deviceMapper.offlineInactiveDevices(offlineThreshold);
        
        // 记录日志
        log.info("Device status check completed at {}", new Date());
    }
}

graph LR
    A[纯MyBatis] -->|新增模块使用| B[混合架构]
    B -->|核心模块重写| C[全量增强框架]

// 统一DAO接口
public interface UserDao {
    User getById(Long id);
    List<User> searchUsers(UserQuery query);
    Page<User> pageUsers(int pageNum, int pageSize);
    boolean save(User user);
    boolean update(User user);
    boolean delete(Long id);
}

// 多实现注册
@Configuration
public class DaoConfig {
    
    @Bean
    @Primary
    @ConditionalOnProperty(prefix = "dao", name = "type", havingValue = "mybatis-plus")
    public UserDao mybatisPlusUserDao(UserMapper userMapper) {
        return new MybatisPlusUserDao(userMapper);
    }
    
    @Bean
    @ConditionalOnProperty(prefix = "dao", name = "type", havingValue = "tk-mybatis")
    public UserDao tkMybatisUserDao(tkUserMapper userMapper) {
        return new TkMybatisUserDao(userMapper);
    }
    
    @Bean
    @ConditionalOnProperty(prefix = "dao", name = "type", havingValue = "native")
    public UserDao nativeMybatisUserDao(SqlSessionTemplate sqlSession) {
        return new NativeMybatisUserDao(sqlSession);
    }
}

# application.yml
dao:
  type: mybatis-plus # 可切换为 tk-mybatis 或 native

graph TD
    A[项目需求分析] --> B{SQL复杂度}
    B -->|高<br>复杂报表/分析查询| C[选择原生MyBatis]
    B -->|低-中<br>标准CRUD| D{团队环境}
    
    D -->|国内团队<br>中文支持需求| E{功能需求}
    E -->|多租户/逻辑删除/AR模式| F[选择MyBatis Plus]
    E -->|仅需基础CRUD| G[选择tk-mybatis]
    
    D -->|国际团队<br>英文文档需求| H{资源限制}
    H -->|资源受限<br>边缘设备/IoT| I[选择tk-mybatis]
    H -->|资源充足| J[评估MyBatis Plus国际版]
    
    C --> K[保留原生MyBatis]
    F --> L[全面采用MyBatis Plus]
    G --> M[采用tk-mybatis]
    I --> N[采用tk-mybatis]
    J --> O[考虑MyBatis Plus或混合架构]

// MyBatis
userMapper.insert(user);

// MyBatis Plus
userMapper.insert(user); // 或 user.insert()

// tk-mybatis
userMapper.insert(user);

// MyBatis
List<User> users = userMapper.selectByCondition(map);

// MyBatis Plus
List<User> users = userMapper.selectList(
    new LambdaQueryWrapper<User>()
        .eq(User::getAge, 25)
        .like(User::getName, "张")
);

// tk-mybatis
Example example = new Example(User.class);
example.createCriteria()
    .andEqualTo("age", 25)
    .andLike("name", "张%");
List<User> users = userMapper.selectByExample(example);

// MyBatis + PageHelper
PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();

// MyBatis Plus
Page<User> page = new Page<>(1, 10);
userMapper.selectPage(page, null);

// tk-mybatis + PageHelper
PageHelper.startPage(1, 10);
List<User> users = userMapper.selectAll();