Especificaciones de revisión del diseño de la interfaz
Esta especificación de diseño de interfaz hace referencia a algunos de los conceptos de diseño de restfull.
Los recursos son los elementos centrales de Restful API y todas las operaciones se realizan en recursos específicos.
Cualquier cosa a la que sea necesario hacer referencia es un recurso. Un recurso puede ser una entidad (como un número de teléfono móvil) o simplemente un concepto abstracto (como un valor). A continuación se muestran algunos ejemplos de recursos:
Se puede decir que Github es un modelo a este respecto. Tomemos el repositorio como ejemplo.
Podemos ver varias características:
El nombre de la interfaz debe ser simple y claro, y el texto debe explicarse por sí mismo. En la introducción de la interfaz, se describen las funciones comerciales específicas de la interfaz. deben describirse claramente.
En principio, la especificación de nomenclatura de la interfaz adopta la forma de "sustantivo" y "verbo" en su conjunto.
La interfaz devuelve u opera un único objeto de recurso y se nombra en singular. forma del nombre, como: /usuario /add, /usuario/del, /usuario/get
La interfaz devuelve u opera múltiples objetos de recursos, que se nombran en la forma plural del nombre, como como: /users/get
Para la misma interfaz, de acuerdo con las necesidades comerciales reales, para resolver el problema de compatibilidad de la interfaz, la versión de la interfaz se puede expandir. La especificación de nomenclatura tiene la forma de "sustantivo". ", "verbo" y "número de versión". El número de versión se denomina en forma de v1, v2, v3
Ejemplo: /user/login, /user/login/v1
El valor de retorno de la interfaz tendrá el siguiente formato:
{
"sign": "f64b967289ac4d8cbfdc22ad30ec9d09",
"content": "{} ",
"marca de tiempo": 1561204602005,
"desc": " ¡Éxito!",
"código": "000",
"accessToken": "83BAED4DAE9DEF783FDE243F4B5C"
}
signo: verificación de la firma del valor de retorno (si es necesario)
En caso de circunstancias especiales, como terceros -Cooperación entre partes, el diseño se basará en la situación real.
Una interfaz solo hace una cosa
El guión "-" se usa generalmente para separar cadenas (palabras) que aparecen en los URI para mejorar la legibilidad de los URI. Utilice guiones bajos "_". separar cadenas (palabras) puede entrar en conflicto y superponerse con el estilo del enlace, lo que afecta la legibilidad.
Según la definición de RFC3986, el URI distingue entre mayúsculas y minúsculas, por lo que para evitar ambigüedades, intentamos utilizar caracteres en minúscula.
Por ejemplo, para las cantidades, se unifican todas como cantidad, en lugar de una cantidad y un dinero.
Si realiza cambios en la interfaz anterior, debe considerar la compatibilidad de la interfaz, lo que incluye agregar o eliminar campos, ajustar los nombres de los campos, ajustar los tipos de campos, ajustar la longitud del contenido de los valores de los campos y ajustar el rango de valores de los valores del campo espera.
Una vez lanzada la interfaz, no es fácil de modificar. Para mantener la compatibilidad, los errores ortográficos no se pueden cambiar, así que revise la ortografía cuidadosamente.
Tragedia famosa: la creación de Unix.
creat es una función que se puede utilizar para crear un archivo y abrirlo en modo de solo escritura.
Es mejor utilizar sustantivos atributivos al nombrar parámetros
Por ejemplo, fileName, maxSize, textColor, en lugar de nombre, tamaño, color
Hacer. No utilice palabras poco comunes ni utilice Hanyu Pinyin
A menos que sea una abreviatura de uso común que se haya utilizado ampliamente, debe escribirse de manera honesta y completa.
Por ejemplo, si hay una apertura, debe haber un cierre, y si hay un inicio de sesión, debe haber un cierre de sesión. Estas palabras son básicamente una combinación fija y es fácil para los usuarios. entender.
Por ejemplo, si la empresa requiere usuarios VIP, no se permite diseñar la interfaz como isVipUser, pero debe diseñarse para obtener la interfaz de nivel de membresía del usuario, /user/level/get, para garantizar la versatilidad y escalabilidad de la interfaz
p>
La denominación de los parámetros de la interfaz relacionados con la paginación está unificada:
pageSize: el número de registros por página
pageNum: el número de página actual
totalPageNum: total** *Número de páginas
Transmitir uniformemente en minutos
Se recomienda transmitir uniformemente el tiempo en milisegundos para evitar formatos de fecha inconsistentes en el front-end y back-end o en varios escenarios