Qt GRPC Descripción general de los interceptores
Descripción general de los interceptores
Los interceptores del lado del cliente proporcionan un mecanismo ligero para implementar comportamientos que deben aplicarse de forma coherente en numerosas RPC. Resultan especialmente útiles para cuestiones transversales que son independientes de un método RPC específico, tales como:
- Seguimiento distribuido
- Registro
- Autenticación y autorización
- Métricas y observabilidad
- Aplicación de políticas
- Almacenamiento en caché del lado del cliente
- Inyección de fallos
Los interceptores se instalan en un canal mediante un ` QGrpcInterceptorChain`. Cada interceptor implementa una o más interfaces de interceptor (por ejemplo, ` QGrpcStartInterceptor ` y ` QGrpcFinishedInterceptor`). El canal ` Qt GRPC ` invoca la interfaz correspondiente cada vez que se alcanza esa etapa de una RPC, proporcionando el contexto de la RPC actual.
Los interceptores operan a nivel de cada RPC individual. Pueden inspeccionar y modificar los metadatos y las cargas útiles de las solicitudes o respuestas a medida que avanza el RPC. Están pensados para implementar un comportamiento específico por llamada, más que para gestionar la configuración del canal o del transporte.
Nota: Los interceptores de Qt GRPC se instalan en un canal y se aplican a todas las RPC realizadas a través de dicho canal. La cadena de interceptores se fija en el momento de la construcción y no puede modificarse posteriormente. Para cambiar el comportamiento de interceptación, cree un nuevo canal con una cadena de interceptores diferente.
Capacidades y puntos de enganche
Cada interfaz de interceptación representa un punto de enganche en el ciclo de vida del RPC. Una clase de interceptor puede implementar varias interfaces mediante la herencia múltiple.
Qt GRPC detecta qué interfaces de interceptación implementa un interceptor y las expone como capabilities. Qt GRPC utiliza estas capacidades para despachar únicamente los puntos de enganche que están realmente implementados.
| Interfaz | Punto de enganche | Dirección | Puede modificar |
|---|---|---|---|
| QGrpcStartInterceptor | Antes de que se inicie la RPC | Saliente | Objeto de mensaje inicial, opciones de llamada |
| QGrpcWriteMessageInterceptor | Antes de escribir un mensaje saliente | Saliente | Objeto de mensaje |
| QGrpcWritesDoneInterceptor | Cuando el cliente indica que se han realizado las escrituras | Saliente | — |
| QGrpcCancelInterceptor | Cuando se cancela la RPC | Saliente | — |
| QGrpcInitialMetadataInterceptor | Cuando se reciben los metadatos iniciales | Entrante | Metadatos |
| QGrpcMessageReceivedInterceptor | Cuando se recibe la carga útil de un mensaje | Entrante | Datos del mensaje serializados |
| QGrpcTrailingMetadataInterceptor | Cuando se reciben metadatos finales | Entrante | Metadatos |
| QGrpcFinishedInterceptor | Cuando finaliza la RPC | Entrante | Estado final |
Todas las llamadas de retorno reciben un objeto ` QGrpcInterceptionContext`, que proporciona información sobre la RPC interceptada, como el ` RPC descriptor`, el ` channel ` o el ` callOptions ` en vigor. El objeto de contexto solo es válido mientras dura la llamada de retorno y no debe utilizarse posteriormente.
Nota: Mantén la lógica de interceptación ligera y evita las operaciones de bloqueo en las devoluciones de llamada. Realiza las tareas lentas (por ejemplo, E/S o actualización de tokens) fuera de la devolución de llamada y aplica el resultado únicamente en el gancho.
Dirección y flujo
Cuando se utilizan varios interceptores, su orden es importante. Resulta útil imaginar que los interceptores están dispuestos en línea entre la aplicación y la red. Los interceptores situados al principio de la cadena procesan primero la RPC y pueden modificarla antes de pasarla al siguiente interceptor. Los interceptores más cercanos a la red tienen la última oportunidad de observar o ajustar lo que realmente se envía.
Los interceptores se añaden a una cadena de interceptores ( QGrpcInterceptorChain ) en un orden definido. El proceso de llamada a la función de llamada ( QtGrpc ) recorre la cadena a medida que fluye la RPC:
- En las etapas de salida (aplicación → red), las funciones de devolución de llamada se invocan en el orden en que los interceptores se añadieron a la cadena.
- En las etapas de entrada (red → aplicación), las funciones de devolución de llamada se invocan en orden inverso, de modo que el último interceptor, «el más cercano a la red», vea primero los datos entrantes.

Las etapas de salida corresponden a operaciones iniciadas por el cliente, como el envío de un mensaje o la finalización de una secuencia de escritura (por ejemplo, writeMessage o writesDone). Estos eventos viajan desde la aplicación a través de la cadena de interceptores hacia la red.
Las etapas de entrada corresponden a eventos generados por el RPC, como la recepción de un mensaje o la finalización de la llamada (por ejemplo, messageReceived o finished). Estos eventos viajan desde la red, de vuelta a través de la cadena de interceptores, hacia la aplicación.
Propiedad y ciclo de vida
QGrpcInterceptorChain admite dos modelos principales de ciclo de vida:
- Con propiedad: se añaden interceptores mediante `
std::unique_ptr<T>()`. Si se realiza correctamente, la cadena asume la propiedad y destruye los interceptores cuando se destruye la cadena (y, por lo tanto, el canal). - Sin propiedad: se añaden interceptores utilizando punteros sin tipo `
T*`. La cadena no asume la propiedad. El llamante debe asegurarse de que los objetos interceptores sigan siendo válidos mientras el canal pueda invocarlos.
Ambos modelos también pueden combinarse dentro de la misma cadena. Aunque está permitido, mezclar interceptores con propiedad y sin propiedad requiere precaución para garantizar que los interceptores sin propiedad sobrevivan a todos los canales que puedan utilizarlos.
Los interceptores sin propiedad pueden compartirse entre varios canales añadiendo la misma instancia de interceptor a varias cadenas. Esto resulta útil para el registro compartido o la recopilación compartida de métricas, pero requiere una gestión cuidadosa de la vida útil y del acceso simultáneo.
Seguridad de subprocesos y estado compartido
Las llamadas de retorno de los interceptores se ejecutan en el hilo del canal propietario de la cadena de interceptores.
Los interceptores reentrantes no requieren sincronización alguna.
La sincronización solo es necesaria cuando los interceptores acceden a datos compartidos que pueden ser utilizados desde varios hilos. Esto puede ocurrir, por ejemplo, cuando una misma instancia de interceptor es utilizada por canales que residen en diferentes hilos, o cuando varias instancias de interceptor acceden a los mismos datos compartidos.
Cuando sea necesario acceder a datos compartidos entre hilos, es preferible mantener las instancias de interceptor locales al hilo y almacenar los datos compartidos en un objeto sincronizado por separado.
struct SharedData
{
QReadWriteLock lock;
// shared data protected by lock
};
class MyInterceptor : public QGrpcStartInterceptor
{
public:
explicit MyInterceptor(std::shared_ptr<SharedData> data)
: m_sharedData(std::move(data)) {}
Continuation onStart(~~~) override; {
// access shared data here
}
private:
std::shared_ptr<SharedData> m_sharedData;
};
~~~
auto sharedData = std::make_shared<SharedData>();
bool ok = chain1.set(
std::make_unique<MyInterceptor>(sharedData),
std::make_unique<MyInterceptor>(sharedData)
);
// repeats for chain2
~~~
auto channelThread1 = std::make_shared<QGrpcHttp2Channel>(
QUrl("address:port"), std::move(chain1));
auto channelThread2 = std::make_shared<QGrpcHttp2Channel>(
QUrl("address:port"), std::move(chain2));© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.