Краткий справочник API

Аннотации

@Auth

Может применяться к классу контроллера, методу или составной аннотации.

@Auth(
    roles = { "admin", "auditor" },
    permissions = { "report:read" },
    mode = AuthMode.ANY
)

@Anonymous

Помечает класс или метод, для которого аутентификация не требуется. Определение на методе имеет приоритет; данные текущего пользователя не создаются.

AuthPrincipal<T>

Неизменяемые данные аутентифицированного пользователя:

Конструктор защитно копирует наборы и Map. Значение id не может быть пустым.

CurrentAuth

Синглтон-фасад под управлением Spring, использующий контекст потока запроса:

currentAuth.isAuthenticated();
currentAuth.getUserId();
currentAuth.getUser(AppUser.class);
currentAuth.getRoles();
currentAuth.getPermissions();
currentAuth.hasRole("admin");
currentAuth.hasPermission("GET", "/api/users/42");

Если текущий пользователь не установлен, requirePrincipal() выбрасывает IllegalStateException. Обычно его вызывают только на пути, уже защищённом @Auth.

AuthInterceptor<T>

Необходимо реализовать:

AuthPrincipal<T> authenticate(String token, HttpServletRequest request);

Дополнительно можно переопределить resolveToken, authorize, bind, clear и resolveRequestPath. Когда приложение предоставляет такой бин, автоматически настроенный PermitAllAuthInterceptor перестаёт применяться.

ApiResponse<T>

Поля: success, code, message, data, timestamp.

ApiResponse.success(data);
ApiResponse.success("created", data);
ApiResponse.failure("ORDER_CLOSED", "Order is already closed");
ApiResponse.failure("INVALID_LINES", "Some lines are invalid", details);

PageResult<T>

new PageResult<>(items, total, page, pageSize);

Поля: items, total, page, pageSize. Метод getTotalPages() вычисляет общее число страниц с округлением вверх.

Матрица исключений

Все исключения наследуют SmartMvcException и не создают стек вызовов.

new BusinessException(message) использует код по умолчанию BUSINESS_ERROR. При необходимости можно передать собственный бизнес-код, сообщение и details для ожидаемого отказа, который клиент умеет распознать и обработать.