Interceptors

ent interceptors — зеркальное отражение хуков из семнадцатого урока: там был ent.Mutator, здесь ent.Querier; там next.Mutate, здесь next.Query. Интерфейс ent.Interceptor — один метод: Intercept(next ent.Querier) ent.Querier. Интерфейс ent.Querier — тоже один метод: Query(ctx context.Context, query ent.Query) (ent.Value, error). Читается так: интерсептор получает следующий шаг конвейера чтения и возвращает обёртку над ним; вызов next.Query(ctx, query) означает «передай запрос дальше». Забыть этот вызов — значит остановить конвейер: выборка не дойдёт до SQL, клиент повиснет или вернёт пусто — и никакой ошибки вы не увидите, просто тихое «ничего не происходит». Для лаконичности есть адаптеры: ent.InterceptFunc оборачивает функцию вида func(next ent.Querier) ent.Querier в полноценный Interceptor, а ent.QuerierFunc — функцию тела в Querier. Внутри вы получаете query — generic-интерфейс билдера: у него нет Where и Limit, доступ к конкретике даёт type assertion — if uq, ok := query.(*ent.UserQuery); ok. ent.Value — результат: срез сущностей, число Count, скаляр Select. Регистрация: client.Intercept — рантайм-интерсепторы на все типы графа, client.User.Intercept — на один тип, func (User) Interceptors() []ent.Interceptor — на уровне схемы: как Hooks() из семнадцатого урока, встраивается в сгенерированный код и работает у всех клиентов без исключений.

Регистрация повторяет карту хуков из семнадцатого урока, и тот же принцип «схема — место политик, рантайм — место настроек» работает здесь без поправок. client.Intercept(...) — рантайм-интерсепторы всего графа: логи, метрики, лимиты — всё, что не зависит от типа сущности. client.User.Intercept(...) — на один тип: фильтры конкретной схемы, специфичные правки билдера. func (User) Interceptors() []ent.Interceptor — уровень схемы: интерсептор встраивается в сгенерированный код при сборке клиента и исполняется раньше любого рантайм-хука; политика мягкого удаления обязана жить именно здесь, чтобы ни один новый сервис, собравший клиент из ваших схем, не получил выборку без фильтра. Оговорка из документации, знакомая вам по схемным хукам: раз Interceptors() объявлен в схеме — добавьте в main пустой импорт import _ «ваш-модуль/ent/runtime», иначе между схемой и сгенерированным пакетом ent возможен цикл импортов, а переменные рантайма не инициализируются. Порядок внутри одного уровня — порядок регистрации: первый зарегистрированный — внешний слой конвейера, фактическое исполнение SQL — центр луковицы.

Интерсепторы в ent включаются фича-флагом — так же, как privacy в девятнадцатом уроке: без него генератор не выдаст ни часть API, ни сгенерированный пакет. В ent/generate.go добавьте --feature intercept к команде generate: go:generate go run -mod=mod entgo.io/ent/cmd/ent generate --feature intercept ./schema — и запустите go generate из седьмого урока. Флаг приносит сгенерированный пакет intercept — аналог пакета hook для мутаций. Три его звезды. intercept.Func — generic-интерсептор: получает q intercept.Query и правит его без type assertion — один код на все типы графа. intercept.TraverseFunc — траверзер: исполняется не один раз в финале, а на каждом шаге обхода графа. intercept.TraverseUser — типизированный траверзер User: func(ctx, q *ent.UserQuery) error — внутри вам доступен настоящий билдер со всеми Where-предикатами из десятого урока, включая семейство IsNil. Родственный хелпер — ent.QueryFromContext(ctx): достаёт из контекста снапшот запроса, чтобы проверить, задал ли клиент Limit явно, и не перебивать его. Всё это — сахар над той же механикой Intercept/Querier: sugar не отменяет сигнатуру, а экономит type assertion.

Запрос в приложении дрейфует: хендлер собирает билдер, на него насаживаются предикаты, сортировки и With-загрузки из одиннадцатого урока, затем запрос уходит в обходы рёбер и подзапросы, и лишь в конце исполняется. Фильтр, вшитый в одном месте кода, не обязан доезжать до всех веток этого дрейфа — и вот четыре уровня крепления, от самого хрупкого к самому надёжному. Первый — ручной Where в каждом вызове: работает, пока их девять, утечка гарантирована на десятом. Второй — интерсептор типа: исполняется один раз на финальной стадии, правит финальный билдер конкретного типа; для фильтрации одной сущности этого достаточно. Третий — траверзер: исполняется на каждом шаге обхода графа, поэтому фильтр User доезжает и до промежуточных запросов: client.User.Query().QueryGroups() — фильтр применён на шаге User, ещё до того, как выборка групп начнёт собираться. Четвёртый — всё то же самое, но в схеме: гарантия для всех клиентов. Разница интерсептора и траверзера — момент вмешательства: интерсептор — middleware финальной стадии, он видит запрос перед исполнением и строки после; траверзер — на каждом шаге дрейфа, он правит и промежуточные, и финальные запросы до их склейки. Фильтры по умолчанию — траверзеры; логирование и кеш — интерсепторы.

Четыре границы честности. Первая: интерсепторы применяются только к чтению — на мутации они не подписаны, там территория хуков из семнадцатого урока; UpdateOneID не зайдёт в Intercept ни при каких условиях. Вторая: интерсептор фильтрует, но не решает — он прячет строки из выборок, но не отвечает на вопрос «имеет ли этот viewer право вообще»: если клиент без ограничений может вызвать UpdateOneID — фильтр чтения его не остановит; решения Allow/Deny — работа privacy-политик девятнадцатого урока, и на пути запроса политика исполняется раньше интерсепторов. Третья: интерсептор не обязан срабатывать на агрегатах вашей версии — Count и Select в современных версиях проходят через тот же конвейер с интерсепторами, но GroupBy и кастомные Modify-пути исторически были слепыми пятнами; не рассчитывайте вслепую — проверьте на своей версии ent тестом на три строки. Четвёртая: With-загрузки из одиннадцатого урока исполняются через клиент целевого типа, поэтому фильтр User применяется и к WithPosts, и к WithOwner — но помните про дрейф: пост веры пропадёт из WithPosts анны только если вера отфильтрована на своём шаге, а посты всех «живых» авторов останутся в полном составе.

Вы умеете перехватывать чтение: ent.Interceptor и ent.Querier как конвейер с обязательным next.Query, три уровня регистрации — схема, тип, весь граф, фича-флаг intercept и пакет intercept с intercept.Func и траверзерами, мягкое удаление, ставшее автоматическим, и карта дрейфа запросов, на которой видно, какой фильтр где доезжает. Симметрия с семнадцатым уроком полная: хуки — мутации, интерсепторы — чтение. Но и траверзер, и интерсептор фильтруют, не решая: строку можно спрятать из ленты, при этом мутация остаётся доступной любому контексту без viewer-а. Дальше — privacy-политики девятнадцатого урока: ent.Policy с EvalQuery и EvalMutation, решения privacy.Allow, privacy.Deny и privacy.Skip, deny по умолчанию и тесты политики. Домашнее задание ниже превратит ручные предикаты четырнадцатого урока в схемный контракт. Полный план из 25 уроков — на странице курса, мягкое удаление руками — в четырнадцатом уроке, хуки и hook.Reject — в семнадцатом, With-загрузки — в одиннадцатом, предикаты Where — в десятом.