¿Qué es y cómo funciona React Query para sistemas de producción?
Guía práctica sobre qué es y cómo utilizar React Query en sistemas de producción: contratos, verificaciones y espacios para código listo para usar destinados a los equipos que implementan este patrón.
Las notas siguientes reconstruyen un camino práctico a partir de “Started with React Query”. Se da énfasis en los contratos, las verificaciones y los marcadores de posición para código reutilizable, en lugar de en enfoques motivacionales. Al trabajar en la etapa de Resumen, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los elementos generados, defina las verificaciones de éxito y evite completaciones parciales silenciosas.
Estatuto del servidor vs. estatuto del cliente
El estado del servidor en comparación con la fase del cliente funciona mejor cuando se trata como un parámetro medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Mantenga el proceso de renderizado económico y posponga las derivaciones costosas a la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los valores utilizados.
Tradicionalmente, así es como obtenemos datos
Tradicionalmente, así es como funciona mejor la etapa cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Haga que el proceso de renderizado sea económico y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. La memorización prematura puede ocultar errores en los propios.
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
useEffect(() => {
async function fetchUsers() {
try {
setLoading(true) const res = await fetch(
"https://jsonplaceholder.typicode.com/users"
) const data = await res.json() setUsers(data)
} catch (err) {
setError(err)
} finally {
setLoading(false)
}
} fetchUsers()
Con React Query, el código anterior se convierte en:
Con React Query, esta etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el proceso de renderizado sencillo y reserve las operaciones costosas para la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los props obsoletos.
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
if (isLoading) {
return <p>Loading...</p>
} if (error) {
return <p>Something went wrong</p>
} return (
<ul>
{data.map(user => (
<li key={user.id}>
{user.name}
</li>
))}
</ul>
)
}
Con React Query, esta etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y evite completaciones parciales silenciosas.
Entonces, ¿cómo lo utilizamos en la práctica?
Por lo tanto, ¿cómo organizamos y definimos las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código? Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registren los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Coloquen el estado junto al componente que es responsable de la mutación; llevar todo a un almacén global hace que los errores relacionados con los tiempos de ejecución sean más difíciles de detectar.
1. Configuración
En la fase de configuración inicial, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque el estado junto al componente que gestiona la mutación. Al llevar todo a un almacén global, resulta más difícil detectar errores relacionados con los tiempos de ejecución.
npm install @tanstack/react-query
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
2. Obtención de datos con useQuery
Para el proceso de “Obtención de datos con etapa”, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta normal como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Coloque el estado junto al componente que gestiona la mutación. Subir todo a un almacén global hace que los errores de sincronización sean más difíciles de detectar. Para el proceso de “Obtención de datos con etapa”, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite las completaciones parciales silenciosas.
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
2.1. Función de consulta
Al trabajar en la etapa 2.1 Función de consulta, primero anote el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
2.2. Clave de consulta
Al trabajar en la etapa de Clave de Consulta 2x2, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.
3. Caché
Al trabajar en la etapa de 3 cacheo, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización. Al trabajar en la etapa de 3 cacheo, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
4. staleTime
La etapa 4 de staleTime funciona mejor cuando se trata como una superficie medible. Capture un registro óptimo, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. La memorización prematura puede ocultar errores en los valores obsoletos.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
¿Por qué necesitamos staletime??
El enfoque de “¿Por qué necesitamos etapas?” funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga que el proceso de renderizado sea económico y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. Una memorización prematura puede ocultar errores en los valores utilizados.
Comprensión de staleTime
La etapa Understanding staleTime funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los valores obsoletos. La etapa Understanding staleTime funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
staleTime: 5 * 60 * 1000
5. gcTime
Para la etapa 5 de gcTime, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Coloque el estado junto al componente que es responsable de la mutación; llevar todo a un almacén global hace que los errores relacionados con los tiempos de ejecución sean más difíciles de detectar.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
¿Cuál es la diferencia entre staleTime y gcTime?
En la fase de “¿Cuál es la diferencia?”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque el estado junto al componente que es responsable de la mutación. Al llevar todo a un almacén global, resulta más difícil detectar errores relacionados con los tiempos de ejecución.
6. Volver a obtener datos
En la etapa de 6 Refetching, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Coloque el estado junto al componente que gestiona la mutación. Subir todo a un almacén global hace que los errores de sincronización sean más difíciles de detectar. En la etapa de 6 Refetching, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
const { refetch } = useQuery(...)
refetch()
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
7. Mutaciones: Crear, Actualizar, Eliminar
Al trabajar en la etapa de Crear y Actualizar de las 7 Mutaciones, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Considere los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.
async function createUser(user) {
const response = await fetch(
"https://jsonplaceholder.typicode.com/users",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(user),
}
);
if (!response.ok) {
throw new Error("Failed to create user");
}
return response.json();
}
import { useMutation } from "@tanstack/react-query";
function CreateUser() {
const mutation = useMutation({
mutationFn: createUser,
});
return (
<button
onClick={() =>
mutation.mutate({
name: "John Doe",
email: "john@example.com",
})
}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create User"}
</button>
);
}
export default CreateUser;
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
7.1. Estados de las Mutaciones
Al trabajar en la etapa de los 7 estados de mutación, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización.
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
8. Cliente de consultas
Al trabajar en la etapa 8 de Query Client, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Trate los efectos como una sincronización con el mundo exterior, y no como un sustituto de los valores derivados durante la renderización. Al trabajar en la etapa 8 de Query Client, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
9. Invalidación de consultas
La etapa de invalidación de consultas número 9 funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones. La memorización prematura puede ocultar errores en los valores utilizados.
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
mutation.mutate({
userName: "ironman ghimire",
});
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
Invalidar vs. Volver a cargar
La etapa de Invalidate vs Refetch funciona mejor cuando se trata como una superficie medible. Capture una transcripción de éxito, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga que el proceso de renderizado sea económico y posponga las operaciones costosas a la memorización solo después de realizar mediciones. Una memorización prematura puede ocultar errores en los propios.
Conclusión
La etapa de Conclusión funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga los procesos de renderizado económicos y posponga las derivaciones costosas a la memorización solo después de realizar mediciones; una memorización prematura puede ocultar errores en los datos. La etapa de Conclusión funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
Resumen
En la fase TL DR, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando la tarea pasa de un entorno de demostración a uno compartido. Coloque el estado junto al componente que es responsable de la mutación; llevar todo a un almacén global hace que los errores relacionados con los tiempos de ejecución sean más difíciles de detectar.
Lista de verificación operativa
En la fase de lista de verificación operativa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto.
Preferir unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado.
Colocar el estado junto al componente que gestiona la mutación. Al llevar todo a un almacén global, resulta más difícil detectar errores de sincronización.
Escribir un manual breve: cómo rotar claves, cómo vaciar la cola y cómo revertir la última operación de ingreso.
Tratar esta etapa como un contrato entre las entradas y las salidas validadas. Nombrar los artefactos, definir las verificaciones de éxito y rechazar completaciones parciales silenciosas.
Colocar el estado junto al componente que gestiona la mutación. Al llevar todo a un almacén global, resulta más difícil detectar errores de sincronización.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota para el lote 1aa45226c385: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.
Lecturas relacionadas
- De Prototipo a Producción: Lo que Aprendí Al Construir Sistemas Reales de IA Agente — Guía detallada sobre De Prototipo a Producción: Lo que Aprendí Al Construir Sistemas Reales de IA Agente: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.