The trouble in the early stage is to reduce more communication costs in the later stage and reduce rework.

Alignment requirements

Before development, the front and back ends need to align requirements and corresponding interface lists, and interaction modes

The document

Interface documents must be online. Taboo:

  • No oral notice, description, etc., easy to forget
  • Prohibit chat text to send, search records trouble
  • Unauthorized modification of documents is prohibited, and corresponding personnel must be informed
  • Do not have comments, to clarify the meaning of the interface field, to prevent ambiguity

The interface specification

For some specification discussion about interface input and output, the back end can see alibaba Java development manual. PDF

URL parameter length

The length of parameters to be sent through GET requests varies with browsers. The minimum length is 2048 bytes

The data types must be consistent

Do not enumerate the Number type obtained by the front end. After submission, the output type obtained will be String. Keep the data types of different tables consistent as far as possible; otherwise, front-end judgment will be affected

Keep the field names as consistent as possible

The input and output field names should be the same as possible. For example, the parameter names for saving interfaces are different from the parameter names for querying details

  • It is not conducive to front-end understanding. If multiple back-end development connects to one front-end and each interface key of a business field is different, front-end understanding costs are high and conversion understanding is required
  • Not conducive to front-end development, query and save to convert the corresponding field name

Because the field name is occupied, the keyword is different, that is to minimize this situation

Field name style

Can be unified into the lowerCamelCase style, easy to understand and use, for example, the error-message field name can not be used as a variable name

The only index

Make sure that the list array has a unique index, such as ID Code, and so on

Time format

The time format of the front and back ends is YYYY-MM-DD HH: MM: SS and GMT, reducing the communication between the front and back ends

The front-end format is YYYY-MM-DD HH: MM: SS

Null field

The front end input interface parameter generally object attribute values are undefined and null, the front end will filter not to pass, if you need to pass fields please ask the front end to pass null characters “”

The field attribute undefined will be filtered in **JSON ** and will be replaced with null in array, so the backend POST request will not receive the value of undefined field, get request unified front-end filtering

JSON.stringify({key: undefined})
/ / '{}'

JSON.stringify({ x: [10.undefined]});// '{"x":[10,null]}'
Copy the code

The backend output interface data ensures that the fields returned by the interface are not missing. The general value is null: The base type can be set to ” or NULL, and the reference type can be set to [] or {}. If the fields are missing:

  • Could not determine if fields or data are missing
  • Collections or arrays require tedious null-value judgments
// Return null or no return
const result = {
  "status": 200."data": null
}

/ / the front
if(status === 200 && data && data.list){}
Copy the code

How can the front end trust code stability to the conventions of the back end? In fact, there is no limit to the front end to add null value judgment, good specification is a double guarantee, reduce the problems caused by errors on both sides

A list or collection of data

The data list interface returns, if null, an empty array [] or an empty collection {}. Note that arrays and collections of any depth are required

Paging data

  • If the user input parameter is less than 1, the front end returns the first parameter to the back end
  • If the parameter entered by the user is larger than the total number of pages, the backend returns to the last page
const result = {
  "status": 200."data": {
    "list": []."total": 0."pageSize": 10}}Copy the code

Request way

There are three commonly used commits:

  • POST/GET methodsapplication/x-www-form-urlencoded.<form>Default submission methods such as tags
// POST
Content-Type: application/x-www-form-urlencoded

foo=bar&baz=The+first+line.%0D%0AThe+second+line.%0D%0A

// GET after the URL? foo=bar&baz=The%20first%20line.%0AThe%20second%20line.Copy the code
  • POST methodmultipart/form-dataFile upload is a common submission mode
// POST
Content-Type: multipart/form-data; boundary=---------------------------314911788813839

-----------------------------314911788813839
Content-Disposition: form-data; name="foo"

bar
-----------------------------314911788813839
Content-Disposition: form-data; name="baz"

The first line.
The second line.

-----------------------------314911788813839--
Copy the code
  • POST/GET methodsapplication/json, commonly used to request JSON data
// POST
Content-Type: application/json

{"foo": "bar"}

// GET? foo=barCopy the code