Что такое аннотация Table?

Аннотация @Table в JPA/Hibernate

@Table — это аннотация в Java Persistence API (JPA), которая используется в ORM фреймворках (Hibernate, EclipseLink, OpenJPA) для явного определения имени и схемы таблицы БД, на которую будет отображена сущность (entity).

Основное использование

import javax.persistence.Entity;
import javax.persistence.Table;

@Entity
@Table(name = "users")
public class User {
    private Long id;
    private String name;
    private String email;
}

Без аннотации @Table Hibernate будет использовать имя класса как имя таблицы (в данном случае "User"). С аннотацией @Table мы явно указываем, что сущность User отображается на таблицу "users" (множественное число).

Параметры @Table

1. name — имя таблицы

@Entity
@Table(name = "user_accounts")
public class User {
    // Отображается на таблицу user_accounts
}

Это главный параметр. Если его не указать, используется имя класса.

2. schema — схема БД

Для баз данных, поддерживающих схемы (PostgreSQL, Oracle, SQL Server):

@Entity
@Table(name = "users", schema = "public")
public class User {
    // Полное имя таблицы: public.users
}

@Entity
@Table(name = "products", schema = "shop")
public class Product {
    // Полное имя таблицы: shop.products
}

Это особенно полезно при работе с несколькими схемами в одной БД.

3. catalog — каталог БД

Для СУБД, которые используют каталоги (MySQL использует DATABASE):

@Entity
@Table(name = "users", catalog = "myapp_db")
public class User {
    // Полное имя: myapp_db.users
}

4. uniqueConstraints — уникальные ограничения

Определение составных уникальных ключей в таблице:

@Entity
@Table(
    name = "users",
    uniqueConstraints = {
        @UniqueConstraint(columnNames = "email"),
        @UniqueConstraint(columnNames = {"username", "organization_id"})
    }
)
public class User {
    private Long id;
    private String email;           // Уникален
    private String username;        // Уникален вместе с organization_id
    private Long organizationId;
    
    // Это создаст в БД два уникальных индекса:
    // 1. UNIQUE (email)
    // 2. UNIQUE (username, organization_id)
}

5. indexes — индексы

Определение индексов (JPA 2.1+):

@Entity
@Table(
    name = "users",
    indexes = {
        @Index(name = "idx_email", columnList = "email"),
        @Index(name = "idx_username", columnList = "username"),
        @Index(name = "idx_org", columnList = "organization_id", unique = false)
    }
)
public class User {
    private Long id;
    private String email;
    private String username;
    private Long organizationId;
}

Полный пример с Hibernate

@Entity
@Table(
    name = "employees",
    schema = "hr",
    uniqueConstraints = {
        @UniqueConstraint(columnNames = "email", name = "uk_employee_email"),
        @UniqueConstraint(columnNames = {"department_id", "code"}, 
                         name = "uk_dept_code")
    },
    indexes = {
        @Index(name = "idx_dept", columnList = "department_id"),
        @Index(name = "idx_hire_date", columnList = "hire_date")
    }
)
public class Employee {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "employee_code", nullable = false, length = 20)
    private String code;
    
    @Column(name = "first_name", length = 50)
    private String firstName;
    
    @Column(name = "last_name", length = 50)
    private String lastName;
    
    @Column(name = "email", unique = true, length = 100)
    private String email;
    
    @Column(name = "hire_date", nullable = false)
    private LocalDate hireDate;
    
    @Column(name = "department_id")
    private Long departmentId;
}

// Сгенерирует SQL (в PostgreSQL):
/*
CREATE TABLE hr.employees (
    id BIGSERIAL PRIMARY KEY,
    employee_code VARCHAR(20) NOT NULL,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    hire_date DATE NOT NULL,
    department_id BIGINT,
    CONSTRAINT uk_employee_email UNIQUE (email),
    CONSTRAINT uk_dept_code UNIQUE (department_id, code)
);
CREATE INDEX idx_dept ON hr.employees(department_id);
CREATE INDEX idx_hire_date ON hr.employees(hire_date);
*/

Без @Table аннотации

@Entity
public class Order {
    // Hibernate создаст таблицу "Order" вместо "orders"
    // Это не следует стилю именования SQL
}

// vs

@Entity
@Table(name = "orders")
public class Order {
    // Явно указали, что таблица называется "orders"
    // Более профессионально и понятно
}

Особенности и практики

1. Соглашение об именовании

// Хорошая практика: используй snake_case для БД, camelCase для Java
@Entity
@Table(name = "user_profiles")
public class UserProfile {
    @Column(name = "created_at")
    private LocalDateTime createdAt;
    
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
}

2. @Table с наследованием

@Entity
@Table(name = "vehicles")
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "vehicle_type")
public class Vehicle {
    private String manufacturer;
}

@Entity
@DiscriminatorValue("CAR")
public class Car extends Vehicle {
    private int doors;
}

@Entity
@DiscriminatorValue("TRUCK")
public class Truck extends Vehicle {
    private double maxLoad;
}

3. Partition и другие параметры

// В некоторых ORM можно указать дополнительные параметры
@Entity
@Table(name = "events", indexes = {
    @Index(columnList = "created_at")
})
public class Event {
    // Для сложных требований может потребоваться
    // прямая работа с DatabaseMetaData или миграции
}

Когда это обязательно?

1. Когда имя таблицы отличается от имени класса

@Entity
@Table(name = "auth_users") // Класс: User, Таблица: auth_users
public class User { }

2. При работе с legacy БД

// Старая база данных с нестандартными названиями
@Entity
@Table(name = "USR", schema = "LEGACY")
public class User { }

3. При необходимости явного контроля схемы и каталога

@Entity
@Table(name = "users", schema = "public", catalog = "mydb")
public class User { }

Альтернативы

Для более сложного контроля над генерацией схемы используют:

// Через persistence.xml
// Через Liquibase или Flyway миграции
// Через Hibernate naming strategy
@Entity
public class User {
    // Может использовать физическое имя из ImplicitNamingStrategy
}

Выводы

@Table — это аннотация для явного определения отображения сущности на таблицу БД. Основной параметр — name (имя таблицы). Дополнительные параметры позволяют указать schema, catalog, uniqueConstraints и indexes. Использование @Table делает код более явным, улучшает читаемость и упрощает работу с legacy БД. Это лучшая практика всегда указывать @Table для сущностей, даже если имя класса совпадает с таблицей, так как это делает намерения кода очевидными.