教你更优雅地写 API 之规范响应数据

最新推荐文章于 2024-04-23 17:01:24 发布
最新推荐文章于 2024-04-23 17:01:24 发布
阅读量1.1k 收藏 1
点赞数
分类专栏： php 文章标签： php laravel restful api
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u010624132/article/details/111407150
版权

图片

前言

在推出 lumen-api-starter 以后，收到了不少的关注和反馈，先在此感谢各位朋友萌 🤟

关于 lumen-api-starter 的介绍可以参考上一篇是时候使用 Lumen 8 + API Resource 开发项目了！。本篇是在前一篇的基础上，重新整理并独立出了 package，可以同时支持最新版本 Laravel 和 Lumen 项目。

Package 地址：laravel-response
Laravel 版本 Api 开发初始化项目：laravel-api-starter
Lumen 版本 Api 开发初始化项目：lumen-api-starter

回到正题， 在用 Laravel 或 Lumen 写 API 项目前，通常需要先定义一些项目规范，来让后续的开发体验更舒适，包含有：

  • 规范统一响应数据结构：成功操作、失败操作以及异常操作响应
  • 使用枚举来管理项目中的常量，减少 bug，提高扩展性
  • 更有效地记录日志，来提高线上排查问题效率
  • 其他。…（规划中）

实现过程

RESTful 服务最佳实践 ：如何去设计 Http 状态码以及数据返回格式。

思路

  • 尽可能地遵循 Laravel 思维进行扩展，符合一定规范
  • 尽量少的依赖安装，最好是 0 依赖，不额外增加负担
  • 尽量完善的单元测试，保证代码质量（关于使用示例可以跳过下面的介绍直接查看 https://github.com/Jiannei/laravel-response/tree/main/tests 测试用例）
  • 实现需要简洁，使用需要优雅

功能

  • 统一的数据响应格式，固定包含：code、status、data、message、error
  • 内置 Http 标准状态码支持，同时支持扩展 ResponseCodeEnum 来根据不同业务模块定义响应码
  • 响应码 coed 对应描述信息 message 支持本地化，支持配置多语言
  • 合理地返回 Http 状态码
  • 根据 debug 开关，合理返回异常信息、验证异常信息等
  • 支持格式化 Laravel 的 Api Resource、Api Resource Collection、Paginator（简单分页）、LengthAwarePaginator（普通分页）、Eloquent\Model、Eloquent\Collection，以及简单的 array 和 string等格式数据返回
  • 分页数据格式化后的结果与使用 league/fractal （DingoApi 使用该扩展进行数据转换）的 transformer 转换后的格式保持一致，也就是说，可以顺滑地从 Laravel Api Resource 切换到 league/fractal

规范

  • 合适的 Http 状态码，可以让客户端 / 浏览器更好地理解 Http 响应

教你更优雅地写 API 之规范响应数据

  • 格式固定
{
    "status": "success",// 描述 HTTP 响应结果：HTTP 状态响应码在 500-599 之间为”fail”，在 400-499 之间为”error”，其它均为”success”
    "code": 200,// 包含一个整数类型的 HTTP 响应状态码，也可以是业务描述操作码，比如 200001 表示注册成功
    "message": "操作成功",// 多语言的响应描述
    "data": {// 实际的响应数据
        "nickname": "Joaquin Ondricka",
        "email": "lowe.chaim@example.org"
    },
    "error": {}// 异常时的调试信息
}

需求

在不使用任何 package 的情况下，在 Laravel 中响应 API Json 格式数据，通常是下面这个样子：

return response()->json($data, $status, $headers, $options);

但实际开发场景，会有很多种数据返回需求：

  • 更多时候只是简单的成功和失败响应，所以需要有快捷的 success 和 fail 格式化方法
  • 成功响应可能包含有：User::all()、User::first()、UserResource、UserCollection、User::paginate()、User::simplePaginate() 、 Collection和普通的 Array等，希望这些不同类型的数据都能格式化成统一的结构
  • 失败的响应，通常就是根据不同的业务场景，返回不同的错误码和错误描述
  • 异常响应，对于表单验证、Http 等异常情况，能够针对是否开启 debug 有不同响应，并且格式与前面统一

定义业务操作码

namespace App\Repositories\Enums;

use Jiannei\Response\Laravel\Repositories\Enums\ResponseCodeEnum as BaseResponseCodeEnum;

class ResponseCodeEnum extends BaseResponseCodeEnum
{
    // 业务操作正确码：1xx、2xx、3xx 开头，后拼接 3 位
    // 200 + 001 => 200001，也就是有 001 ~ 999 个编号可以用来表示业务成功的情况，当然你可以根据实际需求继续增加位数，但必须要求是 200 开头
    // 举个栗子：你可以定义 001 ~ 099 表示系统状态；100 ~ 199 表示授权业务；200 ~ 299 表示用户业务。..
    const SERVICE_REGISTER_SUCCESS = 200101;
    const SERVICE_LOGIN_SUCCESS = 200102;

    // 客户端错误码：400 ~ 499 开头，后拼接 3 位
    const CLIENT_PARAMETER_ERROR = 400001;
    const CLIENT_CREATED_ERROR = 400002;
    const CLIENT_DELETED_ERROR = 400003;

    const CLIENT_VALIDATION_ERROR = 422001; // 表单验证错误

    // 服务端操作错误码：500 ~ 599 开头，后拼接 3 位
    const SYSTEM_ERROR = 500001;
    const SYSTEM_UNAVAILABLE = 500002;
    const SYSTEM_CACHE_CONFIG_ERROR = 500003;
    const SYSTEM_CACHE_MISSED_ERROR = 500004;
    const SYSTEM_CONFIG_ERROR = 500005;

    // 业务操作错误码（外部服务或内部服务调用。..）
    const SERVICE_REGISTER_ERROR = 500101;
    const SERVICE_LOGIN_ERROR = 500102;
}

本地化操作码描述

// resources/lang/zh-CN/enums.php
use App\Repositories\Enums\ResponseCodeEnum;

return [
    // 响应状态码
    ResponseCodeEnum::class => [
        // 成功
        ResponseCodeEnum::HTTP_OK => '操作成功', // 自定义 HTTP 状态码返回消息
        ResponseCodeEnum::HTTP_INTERNAL_SERVER_ERROR => '操作失败', // 自定义 HTTP 状态码返回消息
        ResponseCodeEnum::HTTP_UNAUTHORIZED => '授权失败',

        // 业务操作成功
        ResponseCodeEnum::SERVICE_REGISTER_SUCCESS => '注册成功',
        ResponseCodeEnum::SERVICE_LOGIN_SUCCESS => '登录成功',

        // 客户端错误
        ResponseCodeEnum::CLIENT_PARAMETER_ERROR => '参数错误',
        ResponseCodeEnum::CLIENT_CREATED_ERROR => '数据已存在',
        ResponseCodeEnum::CLIENT_DELETED_ERROR => '数据不存在',
        ResponseCodeEnum::CLIENT_VALIDATION_ERROR => '表单验证错误',

        // 服务端错误
        ResponseCodeEnum::SYSTEM_ERROR => '服务器错误',
        ResponseCodeEnum::SYSTEM_UNAVAILABLE => '服务器正在维护，暂不可用',
        ResponseCodeEnum::SYSTEM_CACHE_CONFIG_ERROR => '缓存配置错误',
        ResponseCodeEnum::SYSTEM_CACHE_MISSED_ERROR => '缓存未命中',
        ResponseCodeEnum::SYSTEM_CONFIG_ERROR => '系统配置错误',

        // 业务操作失败：授权业务
        ResponseCodeEnum::SERVICE_REGISTER_ERROR => '注册失败',
        ResponseCodeEnum::SERVICE_LOGIN_ERROR => '登录失败',
    ],
];

使用示例

成功响应

  • 示例代码
public function index()
{
    $users = User::all();

    return Response::success(new UserCollection($users));
}

public function paginate()
{
    $users = User::paginate(5);

    return Response::success(new UserCollection($users));
}

public function simplePaginate()
{
    $users = User::simplePaginate(5);

    return Response::success(new UserCollection($users));
}

public function item()
{
    $user = User::first();

    return Response::success(new UserResource($user));
}

public function array()
{
    return Response::success([
        'name' => 'Jiannel',
        'email' => 'longjian.huang@foxmail.com'
    ],'', ResponseCodeEnum::SERVICE_REGISTER_SUCCESS);
}
  • 返回全部数据
{
    "status": "success",
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "nickname": "Joaquin Ondricka",
            "email": "lowe.chaim@example.org"
        },
        {
            "nickname": "Jermain D'Amore",
            "email": "reanna.marks@example.com"
        },
        {
            "nickname": "Erich Moore",
            "email": "ernestine.koch@example.org"
        }
    ],
    "error": {}
}
  • 分页数据
{
    "status": "success",
    "code": 200,
    "message": "操作成功",
    "data": {
        "data": [
            {
                "nickname": "Joaquin Ondricka",
                "email": "lowe.chaim@example.org"
            },
            {
                "nickname": "Jermain D'Amore",
                "email": "reanna.marks@example.com"
            },
            {
                "nickname": "Erich Moore",
                "email": "ernestine.koch@example.org"
            },
            {
                "nickname": "Eva Quitzon",
                "email": "rgottlieb@example.net"
            },
            {
                "nickname": "Miss Gail Mitchell",
                "email": "kassandra.lueilwitz@example.net"
            }
        ],
        "meta": {
            "pagination": {
                "count": 5,
                "per_page": 5,
                "current_page": 1,
                "total": 12,
                "total_pages": 3,
                "links": {
                    "previous": null,
                    "next": "http://laravel-api.test/api/users/paginate?page=2"
                }
            }
        }
    },
    "error": {}
}
  • 返回简单分页数据
{
    "status": "success",
    "code": 200,
    "message": "操作成功",
    "data": {
        "data": [
            {
                "nickname": "Joaquin Ondricka",
                "email": "lowe.chaim@example.org"
            },
            {
                "nickname": "Jermain D'Amore",
                "email": "reanna.marks@example.com"
            },
            {
                "nickname": "Erich Moore",
                "email": "ernestine.koch@example.org"
            },
            {
                "nickname": "Eva Quitzon",
                "email": "rgottlieb@example.net"
            },
            {
                "nickname": "Miss Gail Mitchell",
                "email": "kassandra.lueilwitz@example.net"
            }
        ],
        "meta": {
            "pagination": {
                "count": 5,
                "per_page": 5,
                "current_page": 1,
                "links": {
                    "previous": null,
                    "next": "http://laravel-api.test/api/users/simple-paginate?page=2"
                }
            }
        }
    },
    "error": {}
}
  • 返回单条数据
{
    "status": "success",
    "code": 200,
    "message": "操作成功",
    "data": {
        "nickname": "Joaquin Ondricka",
        "email": "lowe.chaim@example.org"
    },
    "error": {}
}

其他快捷方法

Response::accepted();
Response::created();
Response::noContent();

失败响应

不指定 meesage

public function fail()
{
    Response::fail();// 不需要加 return
}
  • 未配置多语言响应描述，返回数据
{
    "status": "fail",
    "code": 500,
    "message": "Http internal server error",
    "data": {},
    "error": {}
}
  • 配置多语言描述后，返回数据
{
    "status": "fail",
    "code": 500,
    "message": "操作失败",
    "data": {},
    "error": {}
}

指定 message

public function fail()
{
    Response::fail('error');// 不需要加 return
}

返回数据

{
    "status": "fail",
    "code": 500,
    "message": "error",
    "data": {},
    "error": {}
}

指定 code

public function fail()
{
    Response::fail('',ResponseCodeEnum::SERVICE_LOGIN_ERROR);
}

返回数据

{
    "status": "fail",
    "code": 500102,
    "message": "登录失败",
    "data": {},
    "error": {}
}

其他快捷方法

Response::errorBadRequest();
Response::errorUnauthorized();
Response::errorForbidden();
Response::errorNotFound();
Response::errorMethodNotAllowed();
Response::errorInternal();

异常响应

对于异常的数据格式化，需额外在 app/Exceptions/Handler.php 中 引入 use Jiannei\Response\Laravel\Support\Traits\ExceptionTrait; 引入以后，对于 ajax 请求产生的异常都会进行格式化数据返回。

（Lumen 中为达到同样效果，还需在 app/Http/Controllers/Controller.php 中引入 ExceptionTrait）

  • 表单验证异常
{
    "status": "error",
    "code": 422,
    "message": "验证失败",
    "data": {},
    "error": {
        "email": [
            "The email field is required."
        ]
    }
}
  • Controller 以外抛出异常返回

可以直接使用 abort 辅助函数直接抛出 HttpException  异常

abort(ResponseCodeEnum::SERVICE_LOGIN_ERROR);

// 返回数据

{
    "status": "fail",
    "code": 500102,
    "message": "登录失败",
    "data": {},
    "error": {}
}
  • 其他异常

开启 debug

{
    "status": "error",
    "code": 404,
    "message": "Http not found",
    "data": {},
    "error": {
        "message": "",
        "exception": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException",
        "file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/AbstractRouteCollection.php",
        "line": 43,
        "trace": [
            {
                "file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/RouteCollection.php",
                "line": 162,
                "function": "handleMatchedRoute",
                "class": "Illuminate\\Routing\\AbstractRouteCollection",
                "type": "->"
            },
            {
                "file": "/home/vagrant/code/laravel-api-starter/vendor/laravel/framework/src/Illuminate/Routing/Router.php",
                "line": 646,
                "function": "match",
                "class": "Illuminate\\Routing\\RouteCollection",
                "type": "->"
            },
            ...
        ]
    }
}

关闭 debug

{
    "status": "error",
    "code": 404,
    "message": "Http not found",
    "data": {},
    "error": {}
}

One more thing?

回顾一下，这些封装全部都是基于 response()->json() ，即返回的是 JsonResponse 对象，所以我们依旧可以继续链式调用该对象上的方法。

// 设置 HTTP 响应码
return Response::success(new UserResource($user))->setStatusCode(ResponseCodeEnum::HTTP_CREATED);

其他

依照惯例，如果对您的日常工作有所帮助或启发，欢迎三连 star + fork + follow。

如果有任何批评建议，通过邮箱（longjian.huang@foxmial.com）的方式可以联系到我。

总之，欢迎各路英雄好汉。

QQ 群：1105120693

阿昀.
关注
  • 0
    点赞
  • 踩
  • 1
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
专栏目录
Vue 使用typescript如何优雅的调用swagger API
10-14
这种方法简单直接，但当API数量增多时，会导致代码冗余和维护困难，因为每个函数都需要手动检查和处理响应的数据结构。 为了提高代码质量，我们可以进入进阶阶段，利用typescript来定义接口和数据类型。这样不仅...
Dropbox API V2的官方API规范语言
01-27
- **模式定义**：通过定义数据结构（schema），确保请求和响应遵循API规范。 - **错误处理**：提供统一的错误处理机制，帮助开发者优雅地处理API调用中的错误。 - **代码生成**：可以自动生成与API交互的客户端...
HTTP API响应数据规范整理
weixin_30325071的博客
06-25 132
概述 本文档为本人对长期开发API接口所整理的经验总结，如有不完善或不合理的地方，望各位多提意见。 文档目的为规范服务器端API接口，便于服务器端与客户端代码重用。服务器端和客户端可根据实际所定义规范编写序列化和反序列化工具，以便减少一些开发时间。 本文档为个人观点，仅供参考。 HTTP接口 Execute(CUD) 用于client向server发起的POST、PUT和DELETE请...
REST API规范
最新发布
罗小爬的技术宝书
04-23 1590
REST+ JSON已成为Http接口的事实标准，本文给出我平时推荐的REST API规范及相关注意事项。
laravel dingo api接管异常处理 重定义异常格式 另附接口格式函数 200 401 417 422
上官hao的博客
03-25 2027
dingo api出现异常时格式如下 { "message": "Unauthorized", "status_code": 401, "debug": { "line": 173, "file": "", "class": "", "trace": [ ] ...
基于Laravel封装一个强大的请求响应日志记录中间件
weixin_42100387的博客
10-23 667
基于Laravel封装一个强大的请求响应日志记录中间件
vue 使用axios 数据请求第三方插件的使用教程详解
12-04
Vue.js 是一款流行的前端框架，而...通过这种方式，你可以在Vue应用中优雅地使用axios进行数据请求，同时处理跨域、身份验证等问题。记住，这些配置和用法是基础，实际项目中可能需要根据具体需求进行更复杂的定制。
适用于所有微服务的可扩展、高性能、响应迅速的 API 网关解决方案
04-26
1. 接口定义：定义清晰的API规范，如RESTful或gRPC，确保服务间通信的一致性。 2. 版本控制：支持接口版本管理，方便升级和回滚。 3. 文档生成：自动生成接口文档，供开发者参考。 4. 安全控制：实现API的安全认证和...
详解Koa中更方便简单发送响应的方式
10-18
当API接口越来越多时，如果没有预先定义好统一的响应格式，前端开发者在处理不同格式的响应数据时会遇到困难。这会直接影响到前后端的协作效率以及整个应用的用户体验。因此，像koa2-response这样的中间件不仅提供了...
Laravel如何实现适合Api的异常处理响应格式
12-17
前言 Laravel全局捕获异常后，会把异常转为相应的数据格式返回给用户。如果想要规定的数据格式相应，那我们只需重写异常捕获后的处理方法即可。 异常处理流程 Illuminate\Foundation\Exception\Handler 中的 render 方法用来将异常转化为响应。 public function render($request, Exception $e) { if (method_exists($e, 'render') && $response = $e->render($request)) { return Router::toResponse($request
Lumen 中对 Dingo API 异常接管并自定义响应结果
Right! I'm Max Sky.
06-10 982
场景描述 比如我们需要对 API 限流抛出的异常进行接管，并重写响应消息，首先应用中间件： use Dingo\Api\Routing\Router; $api->group([ 'middleware' => 'api.throttle', // 限流中间件 'expires' => 1, // 时间范围，单位“分” 'limit' => 2, // 时间范围内请求次数 ], function (Router $api) { $api->p
Java后端通用接口设计
weixin_54828627的博客
03-09 2725
为了将接口设计得更合理，我们需要考虑如下两个原则：对外隐藏内部实现。即服务A调用服务B，如果服务B异常，但是我们不要直接把服务B的状态码、错误描述直接暴露给用户；设计接口结构时，明确每个字段的含义，以及客户端的处理方式。接口的设计逻辑：如果出现非 200 的 HTTP 响应状态码，就代表请求没有到服务，可能是网络出问题、网络超时，或者网络配置的问题。这时，肯定无法拿到服务端的响应体，客户端可以给予友好提示，比如让用户重试，不需要继续解析响应结构体。
统一响应结构体 | 大别山码将
weixin_45992021的博客
01-04 1409
在做前后端分离的项目时，后端通常都会拆分成多个独立的微服务，这时候就会涉及每个服务返回给前端的数据格式问题了 在项目中，应该对响应给前端的 JSON 数据的格式进行统一的规定，在很多响应结构中，一般会包含 code、message、data 三个属性。 code 代表状态码，这个不是 HTTP 的响应状态码，而是后端系统的业务状态码，代表了后端响应给前端的业务状态。 message 代表了后端给前端的响应信息，如果发生异常，或者系统错误，会将错误信息存储在 message 中，响应给前端。 data 代表
status code = 404, status message = [Not Found]
热门推荐
qq_45019421的博客
09-20 1万+
Caused by: java.io.IOException: Did not receive successful HTTP response: status code = 404, status message = [Not Found] 求救 服务器端可以正常启动 但是客户端启动时报错 404 找了几个小时 依然无解 具体报错如下图 服务端 文件结构 依赖 <properties> <spring.version>4.0.7.RELEASE</
API请求与响应
精益求精，永无止境，永远在路上！
10-11 2672
API请求与响应前言一、请求构建器 前言 主要讲解如何借助Postman构造接口请求，并分析Postman展示的接口响应信息。 一、请求构建器 在“Builder”选项卡下，请求构建器允许快速创建任何类型的HTTP请求。HTTP请求的4个部分是Method、URL、Headers和Body。Postman提供了方便的工具来处理上述部分，如图所示： （1）Method 使用下拉菜单，更改请求方法非常简单。请求体编辑器区域将根据方法的变化而变化。不同请求方法的可编辑区域不同（如使用GET方法时Body标签置灰
AbstractCollection抽象类
彬
04-05 265
AbstractCollection抽象类第1部分 AbstractCollection抽象类介绍第2部分 AbstractCollection数据结构第3部分 AbstractCollection源码解析(基于JDK-8u201) 第1部分 AbstractCollection抽象类介绍 AbstractCollection简介 1 2 AbstractCollection构造函数 修饰...
api接口返回统一数据格式 status、message、data
A9925的专栏
08-08 8804
/** * [apiReturn 用于给app提供接口使用 带有请求结果状态表示,和结果提示，默认返回json] * @param [number] $status [请求结果的状态标识，设定后要在文档中给予说明] * @param string $message [请求结果的提示语句] * @param [array] $data [请求返回
API设计规范
小末的博客
02-27 4211
1 端点规范 API端点就是API的URI，例如：https://api.example.com/users/me 优秀的端点设计的重要原则： 容易记忆，URI包含的功能一目了然。 1.1端点的基本设计规范 短小便于输入 人可以读懂 没有大小写混用 方便修改 不会暴露服务架构 规则统一 1.2 HTTP方法和端点 端点和HTTP可以被认定是操作对象和操作方法的关系。 URI...
编写优雅API文档：Swagger在线API文档搭建步骤
"Swagger在线API文档搭建指南" Swagger是一个流行的开源工具，用于设计、构建、...通过规范化的文档，开发者能够更好地理解和使用API，从而提升整体项目质量。尽管编写API文档可能看似枯燥，但其长远的价值不容忽视。
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值