Empezar por el contrato de interfaz de la versión que se va a desplegar
Obtenga la documentación API para su implementación y verifique la dirección del servicio, el método de autenticación, las estructuras de solicitud y respuesta y las capacidades disponibles. OpenAPI es un estándar para describir operaciones, parámetros y modelos de datos HTTP API. Utilice el contrato suministrado con el producto para la integración real.
Esta guía de preparación omite puntos finales Haomai Technology AI Brain, campos de autenticación y nombres de paquetes SDK no verificados. Antes de escribir código, haga que el cliente y los equipos de servicio acuerden el mismo contrato y la versión que cubre.
Lista de verificación mínima del contrato API
| Artículo del contrato | Preguntas para resolver |
|---|---|
| Identidad y permisos | ¿La operación se ejecuta como usuario o como aplicación? ¿Cómo se limita su alcance? |
| Solicitud | Tipos de campos, campos obligatorios, límites de tamaño y restricciones de codificación |
| Respuesta | ¿Cómo se representan los resultados, las fuentes, el estado y la finalización? |
| Calendario y cancelación | ¿Cómo se manejan los tiempos de espera, las cancelaciones y los estados de tareas de larga duración? |
| Fracaso | ¿Qué errores se pueden reintentar? ¿Cuáles requieren diferentes entradas o permisos? |
| Versión | Política de compatibilidad, notificaciones de cambios y cronograma de obsolescencia |
Complete una pequeña prueba de un extremo a otro
- Configure una identidad con privilegios mínimos en un entorno de prueba aislado. Mantenga las credenciales fuera del código de interfaz y de los repositorios de ejemplo.
- Realice una llamada exitosa con una pregunta sintética y conserve una solicitud y respuesta redactadas.
- Cubre entradas no válidas, permisos insuficientes, tiempo de espera y cancelación. Verifique que el cliente muestre un estado de error distinto en lugar de un resultado vacío.
- Pruebe el comportamiento de los campos faltantes y desconocidos con el contrato antes de conectar la interfaz empresarial.
Reintentos de diseño en torno al efecto de una operación
Si se interrumpe la red, puede que el servidor ya haya ejecutado la operación. Antes de reintentar una acción con efectos externos, confirme su idempotencia y compruebe cómo consultar el estado de la tarea. Para las consultas de solo lectura, defina límites, intervalos crecientes entre reintentos y condiciones de cancelación.
En el momento de la aceptación, registre la versión del contrato, la versión del cliente, los casos de prueba y los límites conocidos. Para actualizaciones posteriores, valide los mismos casos antes de aumentar gradualmente el tráfico.
