程序设计规范-接口文档

最新推荐文章于 2024-06-21 18:15:52 发布

归来空空

最新推荐文章于 2024-06-21 18:15:52 发布

阅读量1k

点赞数

分类专栏： # 程序设计规范文章标签：前端

本文链接：https://blog.csdn.net/weixin_43387852/article/details/120906979

版权

程序设计规范专栏收录该内容

1 篇文章 0 订阅

订阅专栏

接口文档的作用与意义

在web项目的前后端分离，开发项目的过程中。作为前后端项目数据交互的渠道–接口，需要由前后端工程师共同定义接口，编写接口文档。大家根据这个接口文档进行开发，直到项目结束前都要一直维护这个文档。
- 接口文档有利于前后端工程师共同进行文件的开发交流
- 在项目维护中或项目人员更迭，方便后期人员查看，维护。

接口的规范

接分为四部分:方法，uri，请求参数，返回参数
- 方法：新增(post),修改(put),删除(delete),获取(get),在开发的过程中，需要指明哪种请求方法。一般我们就采用GET/POST方法。
- uri: 一般放置请求的uri地址即可,不允许出现大写字母
- 请求参数和返回参数,都分为5列：字段，说明，类型，备注，是否必填。字段用于标明返回参数名称，说明用于标明参数含义，
  类型一般标明参数的类型，备注是一些解释，或者写一些例子，便于前端理解。是否必填用于标明参数是否必填。
- 返回参数由若干种情况
  - 只返回接口调用成功还是失败(如新增，删除，修改等),则只有一个结构体:code和message两个参数。
  - 如果需要返回某些参数，则有两个结构体:code/message/data,以及data里写返回的参数,data是object类型。
  - 如果要有返回列表，那么有三个结构体: code/message/data,data里面放置：page/size/total/totalPage/list 5个参数，其中data是object类型，list是Array类型，list里面放object，object里面是具体的参数。

接口文档示例

接口详情：

地址 /student/list
方式 GET
请求参数：

字段说明类型备注是否必填
page 页码 Number 默认1 否
size 页面大小 Number 默认10 否
请求参数示例：
```
{
  "page": 1,
  "size": 10
}
```
返回参数：

字段说明类型备注是否必填
code 接口状态码 Number 成功: 1
失败: 0 是
message 接口信息 String 成功: sucess
失败: 提示信息是
data Object 是
data:

字段说明类型备注是否必填
page 页码 Number 是
size 页码大小 Number 是
totalPage 总页数 Number 是
list 学生列表 Array 是
list:

字段说明类型备注是否必填
id 学生id Number 是
name 姓名 Stirng 是
gender 性别 Number 0: 女生
1: 男生是

地址	/student/list
方式	GET

字段	说明	类型	备注	是否必填
page	页码	Number	默认1	否
size	页面大小	Number	默认10	否

字段	说明	类型	备注	是否必填
code	接口状态码	Number	成功: 1 失败: 0	是
message	接口信息	String	成功: sucess 失败: 提示信息	是
data		Object		是

字段	说明	类型	是否必填
page	页码	Number	是
size	页码大小	Number	是
totalPage	总页数	Number	是
list	学生列表	Array	是

字段	说明	类型	备注	是否必填
id	学生id	Number		是
name	姓名	Stirng		是
gender	性别	Number	0: 女生 1: 男生	是

返回参数示例:

{
   "code": 1,
   "message": "成功",
   "data": {
       "page": 1,
       "size": 10, 
       "totalPage": 10,
       "list": [
           {
             "id": 1,
             "name": "张三",
             "gender": 1
           },{
               "id": 2,
               "name": "李华",
               "gender": 0 
           }        
       ]      
   }   
 }

后端接口开发规范

一般我们可以创建两个类，一个类作为返回基类BaseResp,用于作为返回数据格式的基类。一个类作为错误码枚举类ResultStatus，用于
表示错误状态码及其信息。

一个简单的返回基类如下所示:

package com.quick.utils;

import java.util.Date;

/**
 * @param <T>
 */
public class BaseResp<T> {
    /**
     * 返回码
     */
    private int code;

    /**
     * 返回信息描述
     */
    private String message;

    /**
     * 返回数据
     */
    private T data;

    private long currentTime;

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public Object getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public long getCurrentTime() {
        return currentTime;
    }

    public void setCurrentTime(long currentTime) {
        this.currentTime = currentTime;
    }

    public BaseResp(){}

    /**
     *
     * @param code 错误码
     * @param message 信息
     * @param data 数据
     */
    public BaseResp(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.currentTime = new Date().getTime();
    }

    /**
     * 不带数据的返回结果
     * @param resultStatus
     */
    public BaseResp(ResultStatus resultStatus) {
        this.code = resultStatus.getErrorCode();
        this.message = resultStatus.getErrorMsg();
        this.data = data;
        this.currentTime = new Date().getTime();
    }

    /**
     * 带数据的返回结果
     * @param resultStatus
     * @param data
     */
    public BaseResp(ResultStatus resultStatus, T data) {
        this.code = resultStatus.getErrorCode();
        this.message = resultStatus.getErrorMsg();
        this.data = data;
        this.currentTime = new Date().getTime();
    }
}

一个简单的错误码枚举类如下所示:

package com.quick.utils;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 错误码
 * @author vector
 *
 */
public enum ResultStatus {

    // -1为通用失败（根据ApiResult.java中的构造方法注释而来）
    FAIL(-1, "common fail"),
    // 0为成功
    SUCCESS(0, "success"),

    error_pic_file(3,"非法图片文件"),
    error_pic_upload(4,"图片上传失败"),
    error_record_not_found(5, "没有找到对应的数据"),
    error_max_page_size(6, "请求记录数超出每次请求最大允许值"),
    error_create_failed(7,"新增失败"),
    error_update_failed(8,"修改失败"),
    error_delete_failed(9,"删除失败"),
    error_search_failed(10,"查询失败"),
    error_count_failed(11,"查询数据总数失败"),
    error_string_to_obj(12,"字符串转java对象失败"),
    error_invalid_argument(13,"参数不合法"),
    error_update_not_allowed(14,"更新失败：%s"),
    error_duplicated_data(15,"数据已存在"),
    error_unknown_database_operation(16,"未知数据库操作失败，请联系管理员解决"),
    error_column_unique(17,"字段s%违反唯一约束性条件"),
    error_file_download(18,"文件下载失败"),
    error_file_upload(19,"文件上传失败"),

    //100-511为http 状态码
    // --- 4xx Client Error ---
    http_status_bad_request(400, "Bad Request"),
    http_status_unauthorized(401, "Unauthorized"),
    http_status_payment_required(402, "Payment Required"),
    http_status_forbidden(403, "Forbidden"),
    http_status_not_found(404, "Not Found"),
    http_status_method_not_allowed(405, "Method Not Allowed"),
    http_status_not_acceptable(406, "Not Acceptable"),
    http_status_proxy_authentication_required(407, "Proxy Authentication Required"),
    http_status_request_timeout(408, "Request Timeout"),
    http_status_conflict(409, "Conflict"),
    http_status_gone(410, "Gone"),
    http_status_length_required(411, "Length Required"),
    http_status_precondition_failed(412, "Precondition Failed"),
    http_status_payload_too_large(413, "Payload Too Large"),
    http_status_uri_too_long(414, "URI Too Long"),
    http_status_unsupported_media_type(415, "Unsupported Media Type"),
    http_status_requested_range_not_satisfiable(416, "Requested range not satisfiable"),
    http_status_expectation_failed(417, "Expectation Failed"),
    http_status_im_a_teapot(418, "I'm a teapot"),
    http_status_unprocessable_entity(422, "Unprocessable Entity"),
    http_status_locked(423, "Locked"),
    http_status_failed_dependency(424, "Failed Dependency"),
    http_status_upgrade_required(426, "Upgrade Required"),
    http_status_precondition_required(428, "Precondition Required"),
    http_status_too_many_requests(429, "Too Many Requests"),
    http_status_request_header_fields_too_large(431, "Request Header Fields Too Large"),

    // --- 5xx Server Error ---
    http_status_internal_server_error(500, "系统错误"),
    http_status_not_implemented(501, "Not Implemented"),
    http_status_bad_gateway(502, "Bad Gateway"),
    http_status_service_unavailable(503, "Service Unavailable"),
    http_status_gateway_timeout(504, "Gateway Timeout"),
    http_status_http_version_not_supported(505, "HTTP Version not supported"),
    http_status_variant_also_negotiates(506, "Variant Also Negotiates"),
    http_status_insufficient_storage(507, "Insufficient Storage"),
    http_status_loop_detected(508, "Loop Detected"),
    http_status_bandwidth_limit_exceeded(509, "Bandwidth Limit Exceeded"),
    http_status_not_extended(510, "Not Extended"),
    http_status_network_authentication_required(511, "Network Authentication Required"),

    // --- 8xx common error ---
    EXCEPTION(800, "exception"),
    INVALID_PARAM(801, "invalid.param"),
    INVALID_PRIVI(802, "invalid.privi"),

    //1000以内是系统错误，
    no_login(1000,"没有登录"),
    config_error(1001,"参数配置表错误"),
    user_exist(1002,"用户名已存在"),
    userpwd_not_exist(1003,"用户名不存在或者密码错误"),
        ;
    private static final Logger LOGGER = LoggerFactory.getLogger(ResultStatus.class);


    private int code;
    private String msg;

    ResultStatus(int code, String msg){
        this.code = code;
        this.msg = msg;
    }

    public static int getCode(String define){
        try {
            return ResultStatus.valueOf(define).code;
        } catch (IllegalArgumentException e) {
            LOGGER.error("undefined error code: {}", define);
            return FAIL.getErrorCode();
        }
    }

    public static String getMsg(String define){
        try {
            return ResultStatus.valueOf(define).msg;
        } catch (IllegalArgumentException e) {
            LOGGER.error("undefined error code: {}", define);
            return FAIL.getErrorMsg();
        }

    }

    public static String getMsg(int code){
        for(ResultStatus err : ResultStatus.values()){
            if(err.code==code){
                return err.msg;
            }
        }
        return "errorCode not defined ";
    }

    public int getErrorCode(){
        return code;
    }

    public String getErrorMsg(){
        return msg;
    }

}

参考文章

如何优雅的格式化接口: https://www.jianshu.com/p/12f470170b68.
什么是接口文档，如何写接口，有什么规范？:https://www.zhihu.com/question/52409287

归来空空

关注

0
点赞
踩
3

收藏

觉得还不错? 一键收藏
0
评论
程序设计规范-接口文档

接口文档的作用与意义在web项目的前后端分离，开发项目的过程中。作为前后端项目数据交互的渠道–接口，需要由前后端工程师共同定义接口，编写接口文档。大家根据这个接口文档进行开发，直到项目结束前都要一直维护这个文档。接口文档有利于前后端工程师共同进行文件的开发交流在项目维护中或项目人员更迭，方便后期人员查看，维护。接口的规范接分为四部分:方法，uri，请求参数，返回参数方法：新增(post),修改(put),删除(delete),获取(get),在开发的过程中，需要指明哪种请求方法。
复制链接

扫一扫

专栏目录