Este artículo lo lleva a comprender la especificación de diseño de API abierta en detalle

Escrito al frente:

La especificación OpenAPI (OAS) define una especificación de interfaz RESTful API estándar e independiente del lenguaje, que permite que tanto los desarrolladores como los sistemas operativos vean y comprendan la funcionalidad de un servicio sin acceso al código fuente, la documentación o la inspección del tráfico de red (ambos son conveniente para que los humanos aprendan y lean, y también es conveniente para que lean las máquinas). Cuando una OEA se define correctamente, los desarrolladores pueden comprender e interactuar con los servicios remotos con una lógica de implementación mínima.

Además, la herramienta de generación de documentos puede usar la especificación OpenAPI para generar documentación API, y la herramienta de generación de código puede generar código del lado del servidor y del lado del cliente, código de prueba y otros casos de uso en varios lenguajes de programación.

fondo

La API abierta, como la página de inicio, siempre ha sido la fachada del producto.Si la API abierta no está estandarizada, reducirá la profesionalidad del producto. En el escenario de la nube, muchos usuarios elegirán construir sus propios portales para conectarse a la API abierta de los productos en la nube, lo que nos atrae para construir un mecanismo maduro de API abierta.

Desde una perspectiva comercial, existen algunos principios rectores que nos guían para mejorar el mecanismo de API abierta:

• La interfaz utilizada por la página de inicio y la interfaz proporcionada por la API abierta son el mismo conjunto de interfaces
• Cualquier interfaz de página frontal debe tener una API abierta correspondiente

Recientemente, debido a las necesidades comerciales, el producto en la nube CSB participé en las necesidades de investigación y desarrollo para abrir la API abierta al mundo exterior. Al principio no fue difícil, porque el mecanismo de apertura de la API abierta dentro de Alibaba Cloud es muy maduro, y yo No necesitamos diseñarlo en absoluto, pero esta vez la demanda es principalmente Para algunos escenarios de implementación independientes, necesitamos diseñar un conjunto de especificaciones por nosotros mismos, lo que significa que debemos imponer algunas restricciones normativas en Open API. Perspectiva técnica, Alibaba Cloud tiene muchos estándares abiertos de API para nuestra referencia.Algunos de código abierto La documentación de API abierta del producto también es muy completa.

En resumen, por un lado, tomaré su esencia y, por otro lado, debo considerar la particularidad de la forma de salida de mis propios productos. Este artículo intentará discutir una especificación de API abierta adecuada en torno a muchos factores.

Consideraciones de diseño de API abiertas

¿Qué debería regular exactamente una especificación completa de API abierta?

Desde el punto de vista del diseño, debe considerar: especificación de nombres, especificación de composición, especificación de ruta, especificación de parámetros de entrada y salida, especificación de tipo de datos, especificación de valor de retorno unificado, especificación de código de error y especificación de paginación.

Desde la perspectiva del equipo, si el desarrollo primario e intermedio de back-end y la I + D de front-end en el equipo tienen suficiente experiencia para comprender e implementar la especificación API formulada. Al mismo tiempo, con el flujo de personal, si esta especificación de API abierta se puede transmitir bien.

Desde la perspectiva de la industria, es necesario considerar si el mercado de productos que proporcionan Open API está maduro y si el estilo API ya puede tener una especificación correspondiente.

Desde el punto de vista del producto, el estilo de API adecuado para cada producto es diferente, y lo siguiente se centrará en este punto de vista.

En resumen, es difícil llegar a una conclusión sobre el diseño de API abierta. Antes de presentar la especificación de API abierta que finalmente adopta mi producto, primero hablaré sobre algunos conceptos familiares, como el descanso.

La tranquila guerra de especificaciones

Donde haya gente, habrá ríos y lagos.

Lo mismo es cierto donde hay código.

Si está en el círculo del código, debe haber oído hablar de la especificación tranquila:

• CRUD debe declararse como: POST, DELETE, PUT, PATCH, GET

• Los verbos no deberían aparecer y los verbos se representan uniformemente mediante el método HTTP

• Refleja la abstracción de "recursos"

• Use pathVariable, queryParam, header, statusCode para expresar muchas semánticas comerciales

La especificación relajante parece hermosa, pero si realmente intenta implementarla, definitivamente encontrará algunos problemas similares:

• Tomando como ejemplo la interfaz de inicio de sesión de usuario, es difícil asignar este tipo de interfaz a la adición, eliminación, modificación y consulta de recursos.
• Tome la consulta de la tasa de error de las solicitudes de interfaz en las últimas 7 horas como ejemplo, los escenarios de consulta complejos como graphQL a menudo requieren una estructura json, que no se puede lograr mediante GET, y solo se puede pasar POST

En base a esto, el pliego de descanso poco a poco tiene voces de oposición:

• Obligar a que todas las cosas tengan "recursos" es contrario al sentido común del desarrollo, y es posible que la interfaz no se pueda mapear simplemente agregando, eliminando, modificando y consultando
• La semántica de consulta compleja puede no ser necesariamente expresable con GET

Hay muchos partidarios del estilo descansado que critican estas objeciones, en la comunidad es inevitable que "los que rechazan el estilo descansado son principalmente arquitectos de bajo nivel y programadores front-end y back-end que no quieren hacer progreso.Es un problema humano no saber diseñar.Cuestiones normativas” y comentarios por el estilo. Al mismo tiempo, se sublima el descanso: la recuperación de parámetros complejos debe clasificarse como post en la semántica del descanso, porque este comportamiento no es el posicionamiento de recursos (GET), sino la recuperación de recursos (POST)

Esto obviamente estimuló los nervios de los opositores al estilo sosegado, y dijeron con desdén: Oh, estúpidos sosegados fundamentalistas.

No sé si eres partidario o oponente de Restful? O, neutral.

El debate tranquilo ha terminado por el momento, este debate es puramente ficticio, y los jueces no tienen que preocuparse por eso. No importa cómo se vea tranquilo, puede actuar como una persona neutral en mi discusión a continuación, de lo contrario, el efecto se reducirá a la mitad.

ROA y RPC

El diseño de API no solo tiene una especificación de descanso. Desde una perspectiva más amplia, los estilos de diseño de API principales en realidad se pueden dividir en

• Diseño orientado a los recursos, a saber, ROA (arquitectura orientada a los recursos)
• Diseño orientado a procesos, es decir, RPC (Remote Procedure Call)

Restful es un ejemplo típico del estilo ROA, mientras que el estilo RPC es relativamente menos conocido, pero de hecho, la mayoría de las interfaces del sistema pueden ser de estilo RPC, pero el concepto de estilo RPC no es muy conocido.

Tomando el CRUD del módulo de usuario como ejemplo, compare los siguientes dos estilos:

estilo ROA

CREAR USUARIO (POST)

Request:
POST /users

{
    
    "name": "kirito", "age": 18}

Response:
HTTP 201 Created

{
    
    "id": 1, "name": "kirito", "age": 18}

Consultar usuarios (GET)

Request:
GET /users/1

Response:
HTTP 200 OK

{
    
    "id": 1, "name": "kirito", "age": 18}

Consultar lista de usuarios (GET)

Request:
GET /users

Response:
HTTP 200 OK

{
    
    [{
    
    "id": 1, "name": "kirito", "age": 18}], "next": "/users?offset=1"}

Crear/modificar usuario (PUT)

Request:
PUT /users/1

{
    
    "name": "kirito", "age": 19}

Response:
HTTP 200 OK

{
    
    "id": 1, "name": "kirito", "age": 19}

Modificar usuario (PATCH)

Request:
PATCH /users/1

{
    
    "age": 20}

Response:
HTTP 200 OK

{
    
    "id": 1, "name": "kirito", "age": 20}

eliminar usuario (ELIMINAR)

Request:
DELETE /users/1

Response:
HTTP 204 No Content

El estilo ROA y la especificación de descanso describen lo mismo. Para facilitar la comparación con la interfaz de estilo RPC, aquí hay algunos puntos notables del ejemplo anterior:

• Utilice los códigos de respuesta HTTP (200, 201, 204) para completar la asignación entre la semántica HTTP y la semántica comercial, y también aparecerán flujos de excepción 404, 401, etc. (Por cuestiones de espacio, este artículo no presenta flujos de excepción)
• La parte PATCH modifica el recurso y el cuerpo de la solicitud es el contenido de la parte modificada; PUT crea/modifica el recurso y el cuerpo de la solicitud es el contenido completo del nuevo recurso
• id es un localizador de recursos, mientras que la edad y el nombre son atributos

estilo RPC

CREAR USUARIO (POST)

Request:
POST /user/createUser

{
    
    "name": "kirito", "age": 18}

Response:
HTTP 200 OK

{
    
    "code": 0, "message": "", "data": {
    
    "id": 1, "name": "kirito", "age": 18}}

usuario de consulta (POST)

Request:
POST /user/getUser

{
    
    "id": 1}

Response:
HTTP 200 OK

{
    
    "code": 0, "message": "", "data": {
    
    "id": 1, "name": "kirito", "age": 18}}

Consultar lista de usuarios (POST)

Request:
POST /user/listUsers

Response:
HTTP 200 OK

{
    
    "code": 0, "message": "", "data": {
    
    "user": [{
    
    "id": 1, "name": "kirito", "age": 18}], "next": "/user/listUsers?offset=1"}}

modificar usuario (POST)

Request:
POST /user/modifyUser

{
    
    "id": 1, "name": "kirito", "age": 19}

Response:
HTTP 200 OK

{
    
    "code": 0, "message": "", "data": {
    
    "id": 1, "name": "kirito", "age": 19}}

Modificar nombre de usuario (POST)

Request:
POST /user/modifyUserAge

{
    
    "id": 1, "age": 20}

Response:
HTTP 200 OK

{
    
    "code": 0, "message": "", "data": {
    
    "id": 1, "name": "kirito", "age": 20}}

eliminar usuario (ELIMINAR)

Request:
POST /user/deleteUser

{
    
    "id": 1}

Response:
{
    
    "code": 0, "message": ""}

El estilo RPC no es como el estilo tranquilo ROA. Hay algunas convenciones y especificaciones. Cada sistema de negocios tiene diferencias cuando se implementa. Por lo tanto, esta es solo la experiencia personal del autor. Espero que los lectores puedan buscar puntos en común mientras se reservan las diferencias:

• usuario es el nombre del módulo, no es necesario usar la forma plural como el estilo ROA
• Use una estructura clara de verbo-objeto en lugar de asignar CRUD al método HTTP, el método HTTP usa POST de manera uniforme y los escenarios de consulta también pueden usar GET
• El valor devuelto lleva código, mensaje y datos para mapear el estado de la respuesta y la información de la respuesta. Generalmente, usted mismo puede definir el código de estado del código. En este artículo, 0 se usa para indicar que la solicitud es exitosa. El mensaje es solo significativo cuando falla la respuesta empresarial y los datos representan el resultado de la respuesta empresarial

La forma de elegir RPC y ROA debe decidirse de acuerdo con la situación comercial del producto en sí. Existen los siguientes principios rectores:

• Para las API con lógica empresarial compleja, se debe usar el estilo RPC cuando no se pueden usar descripciones simples de adición, eliminación, modificación y consulta.
• Si el estándar de la industria del negocio requiere una API o ROA de estilo relajante para satisfacer las necesidades comerciales, se debe usar el estilo ROA.

AWS adopta principalmente el estilo RPC, Azure y Google adoptan principalmente el estilo ROA (descanso), y Alibaba Cloud OpenAPI admite tanto RPC como ROA, con RPC como método principal.

Aunque la especificación es inocente, he visto muchas "trampas" en la práctica del estilo ROA:

• Requerir recursos primero, es decir, diseñar primero los recursos, luego diseñar la interfaz, que tiene requisitos más altos para el proceso de desarrollo de software.
• Caso de diseño de ROA erróneo 1: al procesar la solicitud HTTP del método DELETE, los servidores de aplicaciones como Tomcat no permiten que el cuerpo de la solicitud se lleve de manera predeterminada y deben habilitarse explícitamente, lo que genera una falla en la eliminación. (Este caso es un problema para el diseñador. Para escenarios de eliminación complejos, no debe asignarse a DELELE, pero debe cambiarse a POST. DELETE no debe llevar un cuerpo de solicitud).
• Caso 2 de diseño de ROA incorrecto: los parámetros transportados en la ruta tranquila pueden causar problemas de coincidencia regulares, como el uso incorrecto del buzón como parámetro de ruta, o el problema de conflicto de la coincidencia de ruta de varios niveles (este caso es el problema del diseñador, escenario de consulta complejo, no debe asignarse a GET, pero debe cambiarse a POST, solo los localizadores de recursos deben aparecer en la ruta y los atributos no deben llevarse)
• Cuando el código de respuesta es 404, es difícil distinguir si la ruta real no existe o el recurso no existe.
• No es propicio para escenarios en los que es necesario configurar el enrutamiento y el reenvío, como conectarse a una puerta de enlace

CSBLa especificación de API abierta espera cumplir con los siguientes requisitos:

• Al desarrollar y diseñar interfaces en el back-end, hay una idea de diseño clara, para que no se enrede con si una interfaz se implementa con POST o GET, y no necesita dedicar demasiado tiempo a la abstracción. de recursos (esto no significa que los recursos no necesiten ser diseñados)
• Cuando el front-end desarrolla la interfaz de acoplamiento, puede cooperar rápidamente con el back-end y facilitar la encapsulación de la interfaz del front-end.
• Cuando los usuarios se conectan a la API abierta, el estilo general es consistente y los módulos son claros

Para resumir, en términos de selección de estilo de diseño, planeo adoptar la especificación de diseño RPC. Para resumir las ventajas del estilo RPC:

• El diseño de API es menos difícil y fácil de implementar
• La mayoría de los productos de capa IAAS maduros de Alibaba Cloud utilizan la especificación RPC
• Adecuado para escenarios de negocios complejos

Un ejemplo detallado de un documento de interfaz RPC

crear servicio

solicitar parámetros

número de serie	Campo nombre chino	Nombre de campo en inglés	tipo de datos	requerido	ilustrar
1	nombre	nombre	cadena	Sí	nombre para mostrar
2	protocolo	protocolo	cadena	Sí	Hojas: http/grpc/webservice
3	balanceo de carga	libras	cadena	Sí	Valor de enumeración: random/roundrobin
4	tipo aguas arriba	upstreamType	cadena	Sí	Valor de enumeración: fijo/descubrimiento
5	lista de nodos	nodos	formación	No	Requerido cuando upstreamType=fixed, ejemplo: [{“host”: “1.1.1.1”, “port”: “80”, “weight”: “1”}]
6	identificación de la fuente	Origen Identificación	cadena	No
7	Nombre del Servicio	Nombre del Servicio	cadena	No	El nombre en el registro, requerido cuando upstreamType=discovery
8	Descripción del servicio	descripción	cadena	No
9	ID de puerta de enlace	ID de puerta de enlace	cadena	Sí

parámetro de retorno

número de serie	Campo nombre chino	Nombre de campo en inglés	tipo de datos	ilustrar
1	código de respuesta	código	En t	0
2	mensaje de respuesta	mensaje	cadena
3	resultado de la respuesta	datos	cadena	ID de servicio de devolución

ejemplo de solicitud

POST /service/createService

Request:
{
    
    
  "name": "httpbin",
  "protocol": "http",
  "lb": "random",
  "upstreamType": "fixed",
  "nodes": [
    {
    
    
      "host": "httpbin.org",
      "port": "80",
      "weight": "1"
    }
  ],
  "gatewayId": "gw-1qw2e3e4"
}

Response:
{
    
    
  "code": 0,
  "message": "",
  "serviceId": "s-1qw2e3e4"
}

Convención de nomenclatura de API

• La API debe usar el inglés con la ortografía correcta y cumplir con las normas gramaticales, incluidas las convenciones del singular y el plural, el tiempo y el idioma.

• No puede haber varias API con significados similares pero sin una diferencia real en la función, como la presencia de /user/getUser y /user/describeUser al mismo tiempo

• Hábitos lingüísticos: el pinyin está prohibido

• Las reglas de nomenclatura de los siguientes escenarios comunes son fijas

  • Los parámetros de tipo datetime deben nombrarse XxxxTime. Por ejemplo:CreateTime

• Especificación de nombre de operación común

  • create:crear
  • modify:cambiar
  • delete:borrar
  • get: Obtener los detalles de un solo recurso
  • list: obtener la lista de recursos
  • establishRelation: Crear una relación de recursos
  • destroyRelation: destruir la relación de recursos

Resumir

Cuando discutimos tales normas, debemos seguir pensando en su propósito y contexto. En un entorno de producción real, tenemos que enfrentar una gran cantidad de código y una demanda creciente, por lo que debemos encontrar una manera de mejorar la eficiencia de la colaboración y la confiabilidad del código para garantizar que podamos satisfacer mejor las necesidades de los clientes.

El uso de la interfaz POST es un método de interfaz común y estándar , que puede minimizar el costo de comunicación entre los usuarios y los desarrolladores, reducir la necesidad de una comprensión adicional de la interfaz y también evitar la interfaz "GET" que puede causar problemas de seguridad.

Además, este método de interfaz estandarizada también puede lograr una mejor mantenibilidad, ya que todas las interfaces en el sistema siguen el mismo estándar, los desarrolladores pueden comprender y modificar fácilmente estas interfaces para localizar y resolver el problema.

En resumen, el uso de la interfaz POST es una práctica tranquilizadora y potencialmente rentable. Para los desarrolladores, este enfoque estandarizado les facilitará seguir las especificaciones de diseño de la interfaz y reducir la carga de trabajo innecesaria para completar mejor las tareas de trabajo. Para el sistema y la empresa, este enfoque también puede mejorar la eficiencia del sistema, reducir los costos de mantenimiento y posicionamiento erróneo, lo que hace que todo el equipo sea más eficiente y competitivo.