java spring Boot创建API接口 springboot开发api接口教程

转载

编程梦想编织者 2024-07-17 18:41:09

文章标签 restful风格接口对象入参 java JSON User 文章分类 Java 后端开发

目标

写一套符合规范，并且具有RESTful风格的API接口。

假定

你已会使用Spring Boot 2.x。
你已会使用Gradle构建Spring Boot工程。
你已会基于Spring Boot编写API接口。
你已会使用接口调试工具。

步骤

1、基于Gradle构建Spring Boot示例项目。

2、引入JavaLib。

3、编写接口代码。

4、测试接口。

引入JavaLib

测试版(SNAPSHOT)，都会发布到 JitPack 上，所以，从这里拉取的，都会是最新的，但是需要配置仓库地址。

正式版(RELEASE)，才会推送到 Maven中央。

UserModel

我们用UserModel来存放我们的数据，以便存取。我个人比较喜欢用bean的，如果你喜欢用Map，那也是可以的。不过需要注意的是，需要加@JsonInclude(JsonInclude.Include.NON_NULL) ，他的作用是，如果某个字段为空时，在返回的JSON中，则不显示，如果没有，将为 null。

完整代码如下：

package com.fengwenyi.demojavalibresult.model;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * User Model
 * @author Wenyi Feng
 * @since 2019-02-05
 */
@Data
@Accessors(chain = true)
@JsonInclude(JsonInclude.Include.NON_NULL)
public class UserModel implements Serializable {

    private static final long serialVersionUID = -835481508750383832L;

    /** UID */
    private String uid;

    /** Name */
    private String name;

    /** Age */
    private Integer age;

}

编写接口返回码

这里我们使用 JavaLib 中result模块为我们提供的方法。只需要调用 BaseCodeMsg.app(Integer, String)即可。这里我们只写几个用作示例，完整代码如下：

package com.fengwenyi.demojavalibresult.util;

import com.fengwenyi.javalib.result.BaseCodeMsg;

/**
 * 自定义返回码以及描述信息
 * @author Wenyi Feng
 * @since 2019-02-05
 */
public class CodeMsg {

    /*
    user error
    ------------------------------------------------------------------------------------------------------------*/
    /** 用户不存在 */
    public static final BaseCodeMsg ERROR_USER_NOT_EXIST = BaseCodeMsg.app(10001, "User Not Exist");

    /** UID不能为空 */
    public static final BaseCodeMsg ERROR_USER_UID_NOT_NULL = BaseCodeMsg.app(10002, "User UID Must Not null");

}

BaseCodeMsg

我们看一下源码：

package com.fengwenyi.javalib.result;

/**
 * (基类)返回码及描述信息
 * @author Wenyi Feng
 * @since 2019-01-22
 */
public class BaseCodeMsg {

    /** 返回码 */
    private Integer code;

    /** 返回码描述 */
    private String msg;

    /**
     * 无参数构造方法
     */
    private BaseCodeMsg() {}

    /**
     * 构造方法
     * @param code
     * @param msg
     */
    private BaseCodeMsg(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }


    public static BaseCodeMsg app(Integer code, String msg) {
        return new BaseCodeMsg(code, msg);
    }

    /**
     * 返回码填充
     * @param args 填充内容
     * @return CodeMsgEnum
     */
    public BaseCodeMsg fillArgs(Object ... args) {

        this.msg = String.format(this.msg, args);

        return this;
    }

    /**
     * 获取返回码
     * @return 返回码
     */
    public Integer getCode() {
        return code;
    }

    /**
     * 获取描述信息
     * @return 描述信息
     */
    public String getMsg() {
        return msg;
    }

    /** 成功 */
    public static final BaseCodeMsg SUCCESS = BaseCodeMsg.app(0, "Success");

    /** 失败 */
    public static final BaseCodeMsg ERROR_INIT = BaseCodeMsg.app(-1, "Error");
}

成功的标识是：当 code=0 时。

另外，我们还为你提供了预留字符串替换的方法。比如你想告诉用户某个字段不合法，那么你可以这样：

第一步：在CodeMsg中添加

public static final BaseCodeMsg ERROR_PARAM_ILLEGAL = BaseCodeMsg.app(20001, "Request Param Illegal : %s");

第二步：返回

/**
     * 测试参数错误
     * @return {@link Result}
     */
    @GetMapping("/test-param-error")
    public Result testParamError() {
        return Result.error(CodeMsg.ERROR_PARAM_ILLEGAL.fillArgs("account"));
    }

测试结果：

java spring Boot创建API接口 springboot开发api接口教程_java

编写接口代码

接下来，开始编写我们的接口代码。

首先指明，我们的接口接收和返回的文档格式。

consumes = MediaType.APPLICATION_JSON_UTF8_VALUE
produces = MediaType.APPLICATION_JSON_UTF8_VALUE

再使用 JavaLib 中 Result。完整代码如下：

package com.fengwenyi.demojavalibresult.controller;

import com.fengwenyi.demojavalibresult.model.UserModel;
import com.fengwenyi.demojavalibresult.util.CodeMsg;
import com.fengwenyi.javalib.result.Result;
import org.springframework.http.MediaType;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.*;

import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

/**
 * User Controller : 用户操作
 * @author Wenyi Feng
 * @since 2019-02-05
 */
@RestController
@RequestMapping(value = "/user",
        consumes = MediaType.APPLICATION_JSON_UTF8_VALUE,
        produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class UserController {

    /** 临时存放用户信息 */
    private List userModelList = new ArrayList<>();/**
     * 初始化用户
     */@PostConstructpublic void init() {for (int i = 0; i < 10; i++)
            userModelList.add(new UserModel().setUid(UUID.randomUUID().toString()).setName("u" + i).setAge(10 + i));
    }/**
     * 查询用户列表
     * @return {@link Result}
     */@GetMapping("/list")public Result list() {return Result.success(userModelList);
    }/**
     * 添加用户
     * @param userModel 这里传JSON字符串
     * @return {@link Result}
     */@PostMapping("/add")public Result add(@RequestBody UserModel userModel) {if (userModel != null) {
            userModelList.add(userModel.setUid(UUID.randomUUID().toString()));return Result.success();
        }return Result.error();
    }/**
     * 根据UID获取用户
     * @param uid UID
     * @return {@link Result}
     */@GetMapping("/get/{uid}")public Result getByUid(@PathVariable("uid") String uid) {if (StringUtils.isEmpty(uid))return Result.error(CodeMsg.ERROR_USER_UID_NOT_NULL);for (UserModel userModel : userModelList)if (userModel.getUid().equals(uid))return Result.success(userModel);return Result.error(CodeMsg.ERROR_USER_NOT_EXIST);
    }
}

测试

1、启动

java spring Boot创建API接口 springboot开发api接口教程_restful风格接口对象入参_02

2、list

访问：http://localhost:8080/user/list

{
    "code": 0,
    "msg": "Success",
    "data": [
        {
            "uid": "d8e2dfac-b6e8-46c7-9d43-5bb6bf99ce30",
            "name": "u0",
            "age": 10
        },
        {
            "uid": "87001637-9f21-4bc7-b589-bea1b2c795c4",
            "name": "u1",
            "age": 11
        },
        {
            "uid": "5e1398ca-8322-4a68-b0d2-1eb4c1cac9de",
            "name": "u2",
            "age": 12
        },
        {
            "uid": "e6ee5452-4148-4f6d-b820-9cc24e5c91b5",
            "name": "u3",
            "age": 13
        },
        {
            "uid": "3f428e26-57e1-4661-8275-ce3777b5da54",
            "name": "u4",
            "age": 14
        },
        {
            "uid": "b9d994b4-f090-40de-b0f3-e89c613061f2",
            "name": "u5",
            "age": 15
        },
        {
            "uid": "748d1349-5978-4746-b0c1-949eb5613a28",
            "name": "u6",
            "age": 16
        },
        {
            "uid": "abaadb7c-23fb-4297-a531-0c490927f6d5",
            "name": "u7",
            "age": 17
        },
        {
            "uid": "5e5917a1-8674-4367-94c6-6a3fd10a08d6",
            "name": "u8",
            "age": 18
        },
        {
            "uid": "03ed6a83-0cc0-4714-9d0d-f653ebb3a2eb",
            "name": "u9",
            "age": 19
        }
    ]
}

3、添加数据

java spring Boot创建API接口 springboot开发api接口教程_java_03