Especificación de diseño de interfaz API HTTP

1. Todas las solicitudes utilizan el método POST

• En comparación con la cadena de consulta de get, el uso de post puede admitir tipos complejos de parámetros de solicitud. Por ejemplo, en proyectos diarios, el parámetro de solicitud de obtención es un tipo de matriz.

• Facilite la firma unificada, el cifrado y el procesamiento de registros de solicitudes y respuestas

2. Reglas de URL

• La URL solo puede contener inglés, usar palabras o abreviaturas en inglés, no usar pinyin chino

• Use letras minúsculas para todos los caracteres

• Separe varias palabras con un guión -, como third-login, no usar thirdloginothirdLoginthird_login

• La parte de la ruta de la URL 系统/模块/操作usa el formato, comoims/video/list

  • Sistema, indicando qué servicio en el microservicio es esta interfaz, puede usar la abreviatura
  • Módulos, que representan submódulos del sistema. El nombre del módulo usa el nombre completo del sustantivo y usa la forma singular
  • La operación, que representa una interfaz específica, utiliza la forma de verbo + sustantivo y necesita considerar el singular y el plural. por ejemplo add-user,list-usersdelete-users

3. Cabecera HTTP

• Coloque datos específicos independientes del negocio en encabezados HTTP
• El sistema backend puede manejar alguna lógica común sin involucrar el cuerpo de la solicitud y la respuesta.

4. Cuerpo de solicitud y respuesta

• usar utf-8codificación
• formato JSON
• Si se requiere cifrado, JSON normal se puede cifrar y codificar con base64

5. Código de estado HTTP

• El resultado del procesamiento del negocio no se refleja en el código de estado http, pero está representado por el campo de código de error del cuerpo de la respuesta.
• Solo algunos códigos de estado http indican respuestas independientes del negocio, como
  • 200: El asunto ha sido tramitado, pero el órgano de respuesta indica el éxito o el fracaso de la tramitación
  • 400: Solicitud incorrecta, utilizada principalmente en la verificación de parámetros de solicitud. El desarrollo del cliente debe asegurarse de que se envíe el formato correcto de la solicitud al servidor
  • 401: Autenticación fallida, generalmente no hay token o ningún token caduca
  • 403: Sin permiso para llamar a esta interfaz. El cliente debe ocultar las operaciones para las que el usuario no tiene permiso
  • 500: excepción del servidor

6. Denominación de campos

• JSON proviene del lenguaje javascript, por lo que el nombre del campo sigue el lenguaje javascript, usando lowerCamelCasela ortografía de camello pequeño
• No use enlaces subrayadossnake_case

7. Tipos de datos

Asignación de tipos de datos comunes

• bool: asignado a una cadena, use Y para representar verdadero, N para representar falso
• int: asignado a número
• largo: asignado a cadena, porque el tipo de número de js no puede manejar suficiente rango de valores, dará lugar a varios problemas extraños en proyectos reales
• flotante, doble, decimal: asignado a cadena
• Fecha, hora: mapeado a cadena

Aviso:

• El campo que representa el concepto de ID, usa uniformemente una cadena
• Durante la transmisión de datos, si un determinado campo está vacío, omita este campo directamente para reducir la sobrecarga de la red
• Cuando los datos comerciales del cuerpo de respuesta contienen varias estructuras de datos, se prefiere el formato anidado, como el mensaje creado por el usuario a continuación.

 "item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",

8. Formato del cuerpo de la respuesta

• code El código de error del procesamiento comercial está representado por palabras cortas en inglés que pueden reflejar el tipo de error, usando letras mayúsculas y guiones bajos para separar las palabras. No se recomienda usar números para representar códigos de error, y usar números para representar tablas de códigos de error requiere mantenimiento adicional.