This is the 20th day of my participation in the August Text Challenge.More challenges in August

1. Introduction

Today we talk about the most contact interface, mainly about the interface input parameter, some students said, ah is not the interface input parameter, what is good to talk about, we do not use it, have become the norm; But what I wrote was all the “reality” I heard and saw in my internship company.

In fact, we hope that some new students, or some of the outsourcing industry “veteran”, we have to admit that sometimes we are producing code that is difficult to maintain.

Although this is relative, if the project is written and no maintenance is required and no changes are made, then in theory you can write whatever you want, because no one will ever look at the code again; But does this really happen in reality? If so, I’m sure it’s rare


2. Using Map as an input parameter

When I entered the company, my first task was to get familiar with the project. After I finished the operation, I opened the code and found a large number of such codes in the interface layer:

@PostMapping("/addProject")
public Map addProject(Map map) {
    // Validates a parameter
    if (map.get("id") = =null) {
        throw new Exception();
    }
    // Use faster JSON to turn the map into an object
    Project project = ObjectUtil.ConvertMapToBean(map);
    // The Map is returned to the front end after service processing
    Map result = projectService.add(project);
    return result;
}
Copy the code

First of all, there are a few obvious questions:

  1. Difficult to maintain: interface input parameters are encapsulated by Map. Without interface documentation, it is difficult for the maintainer to know exactly what parameters are being passed in, and it is impossible to debug directly
  2. Parameter verification is long and smelly: need to manually check the parameters, if the need to check many parameters, that parameter verification is not to write a special length?
  3. Inefficient.: Each entry is usedFasterJsonThis greatly reduces the efficiency of the interface, especially when QPS is high
  4. Null pointer exception: it is easy to cause null pointer exception. When the parameters needed in our code are obtained from Map, if the parameter verification is not done well and the parameter is not passed, there will be null pointer exception


When I approached the project leader with these questions, at first I thought it would be a discussion, but I got the reply: “It’s good to develop this way, it makes back-end development a lot easier, let’s do it in less code, in less time! “

Since the project leader insists on using it, it makes sense that this style is everywhere in the code, and even encapsulates a bunch of utility classes to solve the problems associated with using Map.

With these problems, I continued to study further. After a period of time, I found that they did not have interface documents. It was not because they did not want to use Swagger, but because of the encapsulation of Map, Swagger could not be used at all, and the probability of bugs was quite high


3. Why do people still do this

As I understand it, there are three possibilities:

  1. The project leader pursues fast completion of work, not quality, especially for outsourced work. Party B just completes the contract and gives you the code. Who cares about maintenance?
  2. The colleagues of the development project met the tutor of the first situation when they were just learning. They took this situation for granted and accumulated for years. They were unwilling to change and did not want to change, so they became the first person again
  3. “Old man,” I’ll do what you do, change what you do, there’s no such thing as team style is my style, okay


4. What do we do now

Having seen how not to do this, let’s look at what most people do now:

@PostMapping("/students")
public Response<Student> insert(@RequestBody @Validated Student student) {
    return success(studentService.save(student));
}

Copy the code

Now, a business interface might be as straightforward as that, so let’s take a look at what it contains:

  1. Follow RestFul apis and use Post to save operations
  2. Encapsulates the same return objectResponse<Student>The return format is uniform, allowing the front end to encapsulate a uniform receive format
  3. Using the@RequsetBody+ entity class object to receive Json format parameters, what is passed


Here are the benefits:

  1. Parameter calibration: added to the interface input parameter@ValidatedNotes, as long asStudentClass to add the corresponding parameter verification annotation, you can automatically verify the input parameters, non-compliant parameters directly return an error message
  2. Be clear: What is coming in and what is going out, is the maintainer clear
  3. Clear purpose: People who are familiar with RestFul looks at it and basically know what your interface is doing
  4. Interface documentation: Also, this interface can introduce automated interface documentation tools such as Swagger, which can be written in a fraction of the time during development and updated with the same amount of code


5. Write at the end

With the iteration of technology and projects, maybe this phenomenon will become less and less until it disappears, but the idea I want to express is this:

  1. When we encounter technology, we should not blindly use it, but should be compared horizontally, you have to understand, what can he do, what can not do, to leave a way out for the future of their own
  2. You may have to do something wrong, but you need to understand that you’re doing something wrong and try to fix it, like making notes
  3. Try to arm yourself with technology, even if you’re only in the industry for a while, but have a basic work ethic and try not to bury a hole in the future