AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

API接口开发（一）：接口开发返回结果解决方案

2019-12-01 1489
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
本文涉及的产品
公共DNS（含HTTPDNS解析），每月1000万次HTTP解析
云解析 DNS，旗舰版 1个月
全局流量管理 GTM，标准版 1个月
简介： 采用前后端分离的方式进行项目开发，那么前后端交互比较好的方式是采用HTTP+JSON。如何接口返回结果更加简洁，更加优雅，也更加合理，并且让前端开发人员看得明白，后端开发者也并不会因此而增加工作量呢？

摘要

采用前后端分离的方式进行项目开发，那么前后端交互比较好的方式是采用HTTP+JSON。如何接口返回结果更加简洁，更加优雅，也更加合理，并且让前端开发人员看得明白，后端开发者也并不会因此而增加工作量呢？

正文开始

Hello，各位，好久不见了。一直在筹划个人网站2020版本改版的事情，所以，本篇文章，也是2019年最后一篇了，当然，也得花一些心思，争取把我想要说的话，都一一说出来，说明白，说透彻。

采用前后端分离的方式进行项目开发，那么前后端交互比较好的方式是采用HTTP+JSON。如何接口返回结果更加简洁，更加优雅，也更加合理，并且让前端开发人员看得明白，后端开发者也并不会因此而增加工作量呢？

为此，我写了一套关于API接口开发返回结果解决方案， api-result，已将其开源，并上传到中央仓库，欢迎各位批评和指正。

API讲解

实体类

提供了满足各场景使用的实体类，如下：

ResultModel

这个类是基础实体类，有如下属性：

success：返回结果标识，是一个布尔值，true / false（成功 / 失败）

message：描述信息，错误时，可以在这里填写错误的详细信息

data：数据，是一个泛型，可以是数组或者对象等等，成功并且需要返回数据时，才有该参数

ApiResultModel

结构关系如下：

 ResultModel
 └── ApiResultModel

在这个类里面增加了 code 属性，也是一个泛型，你可以自定义你的返回码类型，可以是整数，或者字符串。

PageResultModel

结构关系如下：

 ResultModel
 └── PageResultModel

这个类主要主要分页返回结果，所以，增加了以下属性：

total：数据总条数，Long型

size：每页条数，整数

pages：总页数，Long型

current：当前页，Long型

Helper工具类

帮助我们操作实体类，具体有哪些helper呢？如下：

ResultHelper

ResultHelper是与ResultModel对应的

success(String message)

成功，携带描述信息

success(String message, T data)

成功，携带描述信息和数据

error(String message)

错误，携带详细的描述信息

ApiResultHelper

ApiResultHelper是与ApiResultModel对应的

success(S code, String message)

成功，携带返回码和描述信息

success(S code, String message, T data)

成功，携带返回码、描述信息和数据

error(S code, String message)

错误，携带错误码和详细描述信息

PageResultHelper

PageResultHelper是与PageResultModel对应的

success(String message)

成功，携带描述信息

success(String message, T data)

成功，携带描述信息和数据

success(String message, T data, long total, int size, long pages, long current)

成功，携带描述信息、数据、总数、每页条数、总页数、当前页

error(String message)

错误，携带详细的描述信息

快速入门

我们为你提供了三个实体类，以满足不同场景，ResultModel适用于通常返回结果，ApiResultModel适用于接口开发返回结果，PageResultModel适用于分页返回结果。也分别为这三个实体类提供了各自的Helper，所以，你可以直接使用这些Helper进行返回。当然，我推荐的使用方式是，先为各Helper编写工具类，再通过工具类进行返回，这样可能更加合理定制自己的返回工具类。

利用Helper进行返回

首先我们来看一个简单的示例代码：

/**
 * 添加方法示例
 * @return {@link ResultModel}
 */
@ApiOperation(value = "添加方法示例")
@PostMapping
public ResultModel<?> add() {
  return ResultHelper.success("添加成功");
}

返回结果：

{
  "success": true,
  "message": "添加成功"
}

注：这只是一个接口返回示例，而不是说添加接口应该这样写。

编写返回结果工具类

比如，我们可以写一个ResultUtils工具类来操作ResultHelper。如下示例：

/**
 * 成功示例
 * @return {@link ResultModel}
 */
public static ResultModel <?> success() {
    return ResultHelper.success("Success");
}

使用返回结果工具类

我门就可以调用ResultUtils类里面的方法，如下示例：

/**
* 成功示例
* @return {@link ResultModel}
*/
@ApiOperation(value = "成功示例")
@DeleteMapping
public ResultModel<?> success() {
   return ResultUtils.success();
}

印象结果：

{
 "success": true,
 "message": "Success"
}

使用示例

示例图

测试接口预览

接口示例

Models

Models

返回成功结果示例

/**
 * 删除方法示例
 * @return {@link ResultModel}
 */
@ApiOperation(value = "删除方法示例")
@DeleteMapping
public ResultModel<?> delete() {
    return ResultUtils.success();
}

响应结果：

{
  "success": true,
  "message": "Success"
}

返回失败结果示例

如果操作出错了，我们怎么返回呢？我们来看一下：

/**
 * 修改方法示例
 * @return {@link ResultModel}
 */
@ApiOperation(value = "修改方法示例")
@PutMapping
public ResultModel<?> update() {
    return ResultUtils.error("修改失败");
}

返回结果：

{
  "success": false,
  "message": "修改失败"
}

返回查询结果示例

值得一提的话，就是查询方法了，我们看一下吧

/**
 * 查询方法示例
 * @return {@link ResultModel}
 */
@ApiOperation(value = "查询方法示例")
@GetMapping
public ResultModel<?> get() {
    List<Map<String, String>> list = new ArrayList<>();
    Map<String, String> map1 = new HashMap<>();

    map1.put("name", "张飞");
    map1.put("desc", "燕人张飞");
    list.add(map1);

    Map<String, String> map2 = new HashMap<>();
    map2.put("name", "赵云");
    map2.put("desc", "常山赵子龙");
    list.add(map2);

    Map<String, String> map3 = new HashMap<>();
    map3.put("name", "关羽");
    map3.put("desc", "温酒斩华雄");
    list.add(map3);

    return ResultUtils.success(list);
}

看一下响应结果吧，是否如你所愿：

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "name": "张飞",
      "desc": "燕人张飞"
    },
    {
      "name": "赵云",
      "desc": "常山赵子龙"
    },
    {
      "name": "关羽",
      "desc": "温酒斩华雄"
    }
  ]
}

接口返回数据示例

/**
* 接口返回数据示例
* @return {@link ApiResultModel}
*/
@ApiOperation(value = "接口返回数据示例")
@GetMapping("/api-data")
public ApiResultModel<Integer, ?> apiData() {
   return ApiResultUtils.success(getData());
}

响应结果：

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "name": "张飞",
      "desc": "燕人张飞"
    },
    {
      "name": "赵云",
      "desc": "常山赵子龙"
    },
    {
      "name": "关羽",
      "desc": "温酒斩华雄"
    }
  ],
  "code": 0
}

接口返回失败结果示例

/**
 * API接口错误返回示例
 * @return {@link ApiResultModel}
 */
@ApiOperation(value = "API接口错误返回示例")
@GetMapping("/api-error")
public ApiResultModel<Integer, ?> apiError() {
    return ApiResultUtils.error(1101, "API接口错误返回示例");
}

响应结果：

{
  "success": false,
  "message": "API接口错误返回示例",
  "code": 1101
}

分页返回数据示例

/**
 * 分页返回数据示例
 * @return {@link ApiResultModel}
 */
@ApiOperation(value = "分页返回数据示例")
@GetMapping("/page")
public PageResultModel<?> page() {
    return PageResultUtils.success(getData(), 100, 10, 10, 1);
}

响应结果：

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "name": "张飞",
      "desc": "燕人张飞"
    },
    {
      "name": "赵云",
      "desc": "常山赵子龙"
    },
    {
      "name": "关羽",
      "desc": "温酒斩华雄"
    }
  ],
  "total": 100,
  "size": 10,
  "pages": 10,
  "current": 1
}

工具类示例

返回结果工具类

package com.fengwenyi.api_example.util;

import com.fengwenyi.api_result.helper.ResultHelper;
import com.fengwenyi.api_result.model.ResultModel;

/**
 * 返回结果封装工具类
 * @author Erwin Feng[xfsy_2015@163.com]
 * @since 2019/11/30 13:54
 */
public class ResultUtils {

    /**
     *  成功
     * @return {@link ResultModel}
     */
    public static ResultModel <?> success() {
        return ResultHelper.success("Success");
    }

    /**
     *  成功，携带数据
     * @param data 数据
     * @param <T>  数据的类型
     * @return {@link ResultModel}
     */
    public static <T> ResultModel <T> success(T data) {
        return ResultHelper.success("Success", data);
    }

    /**
     *  错误，携带详细的错误描述信息
     * @param message 详细的错误描述信息
     * @return {@link ResultModel}
     */
    public static ResultModel <?> error(String message) {
        return ResultHelper.error(message);
    }

}

API接口返回结果工具类

package com.fengwenyi.api_example.util;

import com.fengwenyi.api_result.helper.ApiResultHelper;
import com.fengwenyi.api_result.model.ApiResultModel;

/**
 * API接口返回结果工具类
 * @author Erwin Feng[xfsy_2015@163.com]
 * @since 2019/12/1 20:10
 */
public class ApiResultUtils {

    /**
     * 成功，携带返回码和描述信息
     * @return {@link ApiResultModel}
     */
    public static ApiResultModel<Integer, ?> success() {
        return ApiResultHelper.success(0, "Success");
    }

    /**
     * 成功，携带返回码、描述信息和数据
     * @param data 数据
     * @param <T>  数据的类型
     * @return {@link ApiResultModel}
     */
    public static <T> ApiResultModel<Integer, T> success(T data) {
        return ApiResultHelper.success(0, "Success", data);
    }

    /**
     * 出错，携带错误吗和详细描述信息
     * @param code 返回码
     * @param message 相信描述信息
     * @return {@link ApiResultModel}
     */
    public static ApiResultModel<Integer, ?> error(int code, String message) {
        return ApiResultHelper.error(code, message);
    }
}

分页返回结果工具类

package com.fengwenyi.api_example.util;

import com.fengwenyi.api_result.helper.PageResultHelper;
import com.fengwenyi.api_result.model.PageResultModel;

/**
 * 分页返回结果工具类
 * @author Erwin Feng[xfsy_2015@163.com]
 * @since 2019/12/1 20:32
 */
public class PageResultUtils {

    /**
     * 成功，携带分页相关数据以及信息
     * @param data     数据
     * @param total    数据总条数
     * @param size     每页条数
     * @param pages    总页数
     * @param current  当前页
     * @param <T>      数据类型
     * @return {@link PageResultModel}
     */
    public static <T> PageResultModel<T> success(T data, long total, int size, long pages, long current) {
        return PageResultHelper.success("Success", data, total, size, pages, current);
    }

}

解析返回结果示例

这里补充一下，关于如何解析返回的json字符串，谈谈我的看法吧。返回的是一个json格式的字符串，这里我用fastjson来写解析示例。我们通常会将请求数据封装为一个通用方法或者工具类，只需要返回数据，当然，如果失败，或者出现异常，都在这里处理。

常用返回结果解析示例

/**
 * 解析常用返回结果示例
 * @return 数据
 */
public Object parseResult() {
    String result = "";
    ResultModel<?> resultModel = JSON.parseObject(result, ResultModel.class);
    Boolean success = resultModel.getSuccess();
    if (success != null && success) {
        return resultModel.getData();
    } else {
        // 异常信息
        String message = resultModel.getMessage();
        // 异常处理
        throw new DataParseException(message);
    }
}

接口返回结果解析示例

/**
 * 解析接口返回结果示例
 * @return 数据
 */
public Object parseApiResult() {
    String apiResult = "";
    ApiResultModel<?, ?> apiResultModel = JSON.parseObject(apiResult, ApiResultModel.class);
    Boolean success = apiResultModel.getSuccess();
    if (success != null && success) {
        return apiResultModel.getData();
    } else {
        Object code = apiResultModel.getCode();
        String message = apiResultModel.getMessage();
        // 根据接口错误码分别进行处理
        // ...
        return null;
    }
}

分页返回结果解析示例

这里与上面略有不同，因为，增加了一些字段，所以，我们可以借助bean来返回。

/**
 * 解析分页返回结果示例
 * @return {@link PageResultDataBean}
 */
public PageResultDataBean parsePageResult() {
    String pageResult = "";
    PageResultModel<List<?>> pageResultModel = JSON.parseObject(pageResult, PageResultModel.class);
    Boolean success = pageResultModel.getSuccess();
    if (success != null && success) {
        List<?> data = pageResultModel.getData();
        Long total = pageResultModel.getTotal();
        Integer size = pageResultModel.getSize();
        Long pages = pageResultModel.getPages();
        Long current = pageResultModel.getCurrent();
        return new PageResultDataBean()
                .setTotal(total)
                .setSize(size)
                .setPages(pages)
                .setCurrent(current)
                .setData(data);
    } else {
        // 异常信息
        String message = pageResultModel.getMessage();
        // 异常处理
        throw new DataParseException(message);
    }
}

以上，这一切都是否如你所愿呢？欢迎评论留言告诉我。

链接

[1] api-result源码 | github

[2] api-result源码 | 码云

[3] api-result中央仓库

[4] 测试示例代码

文章标签：
云解析DNS
Java
前端开发
fastjson
移动开发
API
数据格式
开发者
JSON
关键词：
API接口
API开发
API解决方案
API开发接口
API返回结果
冯文议
目录
相关文章
buguge
|
4天前
|
API 开发工具 数据库
开发一份API接口，需要注意这些，看你做到了几项
本文介绍了设计API接口时需注意的关键点，包括数字签名、敏感数据加密与脱敏、限流、参数校验、统一返回与异常处理、请求日志记录、幂等设计、数据量限制、异步处理、参数定义、完整文档及开发者对接SDK等内容，旨在帮助开发者设计出安全、稳定、易维护的API接口。
buguge
37 6
开发一份API接口，需要注意这些，看你做到了几项
API小知识
|
11天前
|
JSON 安全 API
如何使用Python开发API接口？
在现代软件开发中，API（应用程序编程接口）用于不同软件组件之间的通信和数据交换，实现系统互操作性。Python因其简单易用和强大功能，成为开发API的热门选择。本文详细介绍了Python开发API的基础知识、优势、实现方式（如Flask和Django框架）、实战示例及注意事项，帮助读者掌握高效、安全的API开发技巧。
API小知识
37 3
如何使用Python开发API接口？
游客moiomvrp3vyac2
|
7天前
|
存储 SQL API
探索后端开发：构建高效API与数据库交互
【10月更文挑战第36天】在数字化时代，后端开发是连接用户界面和数据存储的桥梁。本文深入探讨如何设计高效的API以及如何实现API与数据库之间的无缝交互，确保数据的一致性和高性能。我们将从基础概念出发，逐步深入到实战技巧，为读者提供一个清晰的后端开发路线图。
游客moiomvrp3vyac2
26 10
游客5fdji2pvmf8888
|
6天前
|
JSON 前端开发 API
后端开发中的API设计与文档编写指南####
本文探讨了后端开发中API设计的重要性，并详细阐述了如何编写高效、可维护的API接口。通过实际案例分析，文章强调了清晰的API设计对于前后端分离项目的关键作用，以及良好的文档习惯如何促进团队协作和提升开发效率。 ####
游客5fdji2pvmf8888
27 5
API小知识
|
4天前
|
JSON API 数据格式
如何使用Python开发1688商品详情API接口？
本文介绍了如何使用Python开发1688商品详情API接口，获取商品的标题、价格、销量和评价等详细信息。主要内容包括注册1688开放平台账号、安装必要Python模块、了解API接口、生成签名、编写Python代码、解析返回数据以及错误处理和日志记录。通过这些步骤，开发者可以轻松地集成1688商品数据到自己的应用中。
API小知识
19 1
winx_19970108018
|
5天前
|
JSON API 数据格式
淘宝 / 天猫官方商品 / 订单订单 API 接口丨商品上传接口对接步骤
要对接淘宝/天猫官方商品或订单API，需先注册淘宝开放平台账号，创建应用获取App Key和App Secret。之后，详细阅读API文档，了解接口功能及权限要求，编写认证、构建请求、发送请求和处理响应的代码。最后，在沙箱环境中测试与调试，确保API调用的正确性和稳定性。
winx_19970108018
20 1
API小知识
|
7天前
|
监控 搜索推荐 安全
探究亚马逊详情API接口：开发与应用
在数字化时代，亚马逊作为全球领先的电商平台，为商家和消费者提供了丰富的商品信息和便捷的购物体验。本文深入探讨了亚马逊详情API接口的获取与运用，帮助开发者和商家实时监控商品数据、分析市场趋势、优化价格策略、分析竞争对手、构建推荐系统及自动化营销工具，从而在竞争中占据优势。文章还提供了Python调用示例和注意事项，确保API使用的安全与高效。
API小知识
30 3
API小知识
|
11天前
|
缓存 监控 Java
如何运用JAVA开发API接口？
本文详细介绍了如何使用Java开发API接口，涵盖创建、实现、测试和部署接口的关键步骤。同时，讨论了接口的安全性设计和设计原则，帮助开发者构建高效、安全、易于维护的API接口。
API小知识
35 4
土木林森
|
10天前
|
XML JSON API
【PHP开发专栏】PHP RESTful API设计与开发
随着互联网技术的发展，前后端分离成为Web开发的主流模式。本文介绍RESTful API的基本概念、设计原则及在PHP中的实现方法。RESTful API是一种轻量级、无状态的接口设计风格，通过HTTP方法（GET、POST、PUT、DELETE）操作资源，使用JSON或XML格式传输数据。在PHP中，通过定义路由、创建控制器、处理HTTP请求和响应等步骤实现RESTful API，并强调了安全性的重要性。
土木林森
18 2
叫个什么名字
|
17天前
|
前端开发 关系型数据库 API
深入浅出后端开发——从零到一构建RESTful API
本文旨在为初学者提供一个关于后端开发的全面指南，特别是如何从零开始构建一个RESTful API。我们将探讨后端开发的基本概念、所需技术栈、以及通过实际案例展示如何设计和实现一个简单的RESTful API。无论你是完全的新手还是有一定编程基础的开发者，这篇文章都将为你提供实用的知识和技巧，帮助你在后端开发的道路上迈出坚实的一步。
叫个什么名字
42 3

热门文章

最新文章

  • 1
    ArcGIS API for Silverlight 地图元素点闪烁，线流动显示的处理方式
  • 2
    关于百度地图api测距显示NaN的解决方案
  • 3
    Promise API 简介
  • 4
    Elasticsearch Java API(九)--删除文档的field以及field的属性
  • 5
    linux新的API signalfd、timerfd、eventfd使用说明
  • 6
    1、Windows API函数归总，网络函数、消息函数、文件处理
  • 7
    【ASP.NET Web API教程】2.4 创建Web API的帮助页面
  • 8
    ASP.NET2.0里的web.config配置接口API(转)
  • 9
    Google地图官方API- 在地图上绘图（自定义标记）
  • 10
    探究如何在Linux系统中修改进程资源限制:四种方法调整进程限制，让你的系统高效运行(包含应用层getrlimit和setrlimit API)
  • 1
    第十一篇 前沿趋势与展望：深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3
    107
  • 2
    第九篇 API设计原则与最佳实践
    128
  • 3
    Vue 3.x全面升级指南：Composition API深度探索
    94
  • 4
    结构化克隆API的前世今生：从深拷贝到原生力量structuredClone()
    102
  • 5
    解锁淘宝商品评论API接口：电商数据分析的新视角
    139
  • 6
    探索API接口开发（定制与开发接口）
    130
  • 7
    印刷文字识别产品使用合集之API接口无法调用如何解决
    77
  • 8
    【安全每日一讲】API是什么？解密API背后的奥秘
    86
  • 9
    抖音电商新篇章：douyin.item_get API接口的深度应用
    213
  • 10
    利用Python和Flask构建RESTful API的实战指南
    135

    • 相关电子书

    更多
  • Spring Boot2.0实战Redis分布式缓存
  • CUDA MATH API
  • API PLAYBOOK

    • 相关实验场景

    更多
  • 基于函数计算快速搭建Zblog等传统应用框架
  • 星轨SOP编排中心实战课程
  • 快速体验智能体API应用
  • 基于Assistant Api的旅游助手
  • 配置流程编排实现根据天气情况播放歌曲
    • 下一篇
    阿里云OSS设置跨域访问