Padrões do MyBatis

Use o MyBatis quando o controle SQL e os mapeamentos explícitos forem importantes. Mantenha o SQL legível, faça contratos de mapper pequenos e coloque transações de negócios na camada de serviço. Combine essa habilidade com springboot-patterns para estrutura de aplicação, database-migrations para alterações de esquema, postgres-patterns ou mysql-patterns para SQL específico do motor, e security-review para entrada não confiável e preocupações de controle de acesso.

Quando Ativar

• Adicionando ou revisando interfaces de mapper do MyBatis ou arquivos XML
• Escolhendo entre mappers XML, mappers de anotação e SQL gerado
• Projetando mapeamentos resultMap, joins, coleções aninhadas ou projeções
• Revisando SQL dinâmico, vinculação de parâmetros, paginação ou escritas em lote
• Depurando consultas N+1, instruções lentas, uso de conexão ou bugs de transação
• Integrando MyBatis-Spring ao Spring Boot ou a uma aplicação legada com prioridade em XML

Como Funciona

Use um mapper fino para operações de persistência e mantenha as regras de negócios em um serviço. Um fluxo típico é:

Controller / batch job -> Service (@Transactional) -> Mapper -> Database

• Registre os mappers uma vez, seja com @Mapper em cada interface ou com @MapperScan para um pacote. Não misture abordagens de registro casualmente.
• Mantenha o namespace XML igual ao nome totalmente qualificado da interface do mapper.
• Dê a cada instrução um id estável e descritivo; trate os métodos do mapper como uma API de persistência que pode ser testada independentemente.
• Retorne um DTO de domínio ou projeção para caminhos de leitura em vez de expor um mapa mutável grande quando a forma é conhecida.
• Mantenha as alterações de esquema em migrações. Não faça o startup do mapper criar ou alterar tabelas de produção silenciosamente.

Exemplos

@MapperScan("com.example.user.persistence")
@Configuration
class MyBatisConfig {
}

public interface UserMapper {
  UserSummary findSummaryById(long userId);
}

<mapper namespace="com.example.user.persistence.UserMapper">
  <select id="findSummaryById"
          parameterType="long"
          resultType="com.example.user.persistence.UserSummary">
    SELECT id, display_name AS displayName, status
    FROM users
    WHERE id = #{userId}
  </select>
</mapper>

Vinculação de Parâmetros e Segurança SQL

Use #{...} para valores. O MyBatis o vincula como um parâmetro de prepared-statement. Trate ${...} como texto SQL bruto: ele é apropriado apenas para um valor selecionado de uma lista de permissões fechada e de propriedade da aplicação, como um mapa de coluna de ordenação.

private static final Map<String, String> SORT_COLUMNS = createSortColumns();

private static Map<String, String> createSortColumns() {
    Map<String, String> columns = new HashMap<>();
    columns.put("name", "display_name");
    columns.put("created", "created_at");
    return Collections.unmodifiableMap(columns);
}

String sortColumn = SORT_COLUMNS.getOrDefault(request.sort(), "created_at");
String sortDirection = request.descending() ? "DESC" : "ASC";
// The mapper receives only an allowlisted identifier; user input is never
// passed directly to ${sortColumn} or ${sortDirection}.

<select id="findPage" resultType="com.example.user.persistence.UserSummary">
  SELECT id AS id,
         display_name AS displayName,
         status AS status,
         created_at AS createdAt
  FROM users
  WHERE tenant_id = #{tenantId}
  ORDER BY ${sortColumn} ${sortDirection}
  LIMIT #{limit}
</select>

Derive tenantId do principal autenticado ou de um contexto de tenant do lado do servidor, nunca de um campo de requisição. Autentique o principal e verifique se ele está autorizado para o tenant antes de invocar o mapper; mantenha o predicado tenant_id em SQL como defesa em profundidade.

Se possível, evite ${} inteiramente selecionando entre instruções fixas ou usando um construtor de consulta específico do banco de dados. Nunca interpole a entrada do usuário em um nome de tabela, nome de coluna, ORDER BY, fragmento WHERE ou expressão SQL.

Para múltiplos parâmetros, use um objeto de requisição ou nomes explícitos de @Param:

List<UserSummary> findActive(
    @Param("tenantId") long tenantId,
    @Param("statuses") Set<UserStatus> statuses
);

Não use o elemento externo obsoleto parameterMap. Prefira mapeamentos de parâmetros inline e jdbcType explícitos para valores anuláveis quando o driver JDBC precisar.

XML, Tipos de Resultado e Mapas de Resultado

• Use resultType para um mapeamento simples de um para um cujos rótulos de coluna já correspondem às propriedades de destino.
• Use resultMap quando aliases, manipuladores de tipo, objetos aninhados ou coleções precisarem de mapeamento explícito.

…