Especificação de design de interface API HTTP

1. Todas as solicitações usam o método POST

• Comparado com a string de consulta de get, o uso de post pode suportar tipos complexos de parâmetros de solicitação. Por exemplo, em projetos diários, o parâmetro de solicitação get é um tipo de matriz.

• Facilite a assinatura unificada, criptografia e processamento de log de solicitações e respostas

2. Regras de URL

• A URL só pode conter inglês, use palavras ou abreviações em inglês, não use pinyin chinês

• Use letras minúsculas para todos os caracteres

• Separe várias palavras com um hífen -, como third-login, não use thirdlogin, thirdLoginouthird_login

• A parte do caminho da URL 系统/模块/操作usa o formato, comoims/video/list

  • System, indicando qual serviço no microsserviço é essa interface, você pode usar a abreviatura
  • Módulos, que representam submódulos do sistema. O nome do módulo usa o nome completo do substantivo e usa a forma singular
  • A operação, que representa uma interface específica, utiliza a forma verbo + substantivo, e precisa considerar singular e plural. Por exemplo add-user,list-usersdelete-users

3. Cabeçalho HTTP

• Coloque dados independentes de negócios específicos em cabeçalhos HTTP
• O sistema de back-end pode lidar com alguma lógica comum sem envolver o corpo da solicitação e da resposta

4. Corpo de Solicitação e Resposta

• usar utf-8codificação
• formato JSON
• Se a criptografia for necessária, o JSON normal pode ser criptografado e codificado com base64

5. Código de status HTTP

• O resultado do processamento do negócio não é refletido no código de status http, mas é representado pelo campo de código de erro do corpo da resposta
• Apenas alguns códigos de status http indicam respostas independentes de negócios, como
  • 200: o negócio foi processado, mas o sucesso ou falha do processamento é indicado pelo corpo da resposta
  • 400: Pedido errado, usado principalmente na verificação de parâmetros do pedido. O desenvolvimento do cliente deve garantir que o formato correto da solicitação seja enviado ao servidor
  • 401: Falha na autenticação, geralmente não há token ou nenhum token expira
  • 403: Sem permissão para chamar esta interface. O cliente deve ocultar as operações para as quais o usuário não tem permissão
  • 500: exceção do servidor

6. Nomenclatura de Campo

• JSON vem da linguagem javascript, então a nomenclatura do campo segue a linguagem javascript, usando lowerCamelCasea ortografia de camelo pequeno
• Não use links sublinhadossnake_case

7. Tipos de dados

Mapeamento de tipo de dados comum

• bool: mapeado para string, use Y para representar verdadeiro, N para representar falso
• int: mapeado para o número
• long: mapeado para string, porque o tipo de número de js não pode lidar com um intervalo de valores suficiente, isso levará a vários problemas estranhos em projetos reais
• float, double, decimal: mapeado para string
• Data, hora: mapeado para string

Perceber:

• O campo que representa o conceito de ID, use string uniformemente
• Durante a transmissão de dados, se um determinado campo estiver vazio, omita esse campo diretamente para reduzir a sobrecarga da rede
• Quando os dados de negócios do corpo da resposta contêm várias estruturas de dados, o formato aninhado é preferencial, como a mensagem criada pelo usuário abaixo

 "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 do corpo da resposta

• code O código de erro do processamento de negócios é representado por palavras curtas em inglês que podem refletir o tipo de erro, usando letras maiúsculas e sublinhados para separar as palavras. Não é recomendado usar números para representar códigos de erro e usar números para representar tabelas de códigos de erro requer manutenção adicional.