目录

    在 Web 应用开发的过程中,后端开发人员需要频繁的交付 API 接口,前端开发人员需要频繁的调用 API 接口。为了降低沟通成本、预防可能的安全风险,遵循约定优于配置的原则,有必要规范 API 的接口规范。Restful API 是以资源为核心的 API 设计思路,所有的操作都是针对特定的资源进行。在 SaaS 开发中,推荐使用 Restful API 风格接口,本文主要讨论 Restful API 在 SaaS 开发过程中的一些前置约定。

    1. 请求规范

    1.1 编码方式

    统一采用 charset=utf-8

    Ajax 全局配置

    $.ajaxSetup({
      contentType: "application/json; charset=utf-8"
    });
    

    Axios 全局配置

    axios.defaults.headers.common['Content-Type'] = 'application/json;charset=UTF-8'
    

    1.2 请求方法

    API 的 Method,要符合实际请求的类型。

    动词含义
    GET查看
    POST创建
    DELETE删除
    PUT更新

    具体可以参考文档《RESTful Web Services Cookbook-cn.pdf》 。

    1.3 传参方式

    • GET 请求 参数放在请求路径后以 ? 开头的参数串中,参数以 urlencode 编码。

    • PUT / PATCH / POST 请求 对于复杂数据结构的传参,建议将参数 JSON 编码后放在请求体中。

    1.4 请求参数

    • 批量数据必须排序,例如: ?sortOrder=asc&sortField=created_time
    • 批量数据必须分页,例如:?page=5&pagesize=50
    • 可以批量请求的 API,不允许轮询,例如:?id=1,2,3

    2. 响应规范

    2.1 统一的返回格式

    字段名返回内容描述
    resultTrue/False
    code现阶段可以不使用, 0代表正确,非0 代表不同的错误情况
    data成功时,返回的数据的内容
    message失败时,返回的错误信息
    request_id(可选)标识请求的id(可以自动生成的唯一标识,方便追踪请求记录 uuid )
    {
        'result': True,
        'message': '',
        'data': [],
        'code': 0
    }
    

    2.2 合适的状态码

    建议充分利用 HTTP Status Code 作为响应结果的基本状态码,基本状态码不能区分的 status,再用响应中”约定”的code进行补充。

    • 200 : GET 请求成功,及 DELETE 或 PATCH 同步请求完成,或者 PUT 同步更新一个已存在的资源
    • 201 : POST 同步请求完成,或者 PUT 同步创建一个新的资源
    • 401 : Unauthorized : 用户未认证,请求失败
    • 403 : Forbidden : 用户无权限访问该资源,请求失败
    • 429 : Too Many Requests : 因为访问频繁,你已经被限制访问,稍后重试
    • 500 : Internal Server Error : 服务器错误,确认状态并报告问题

    http状态码详细说明请参考: https://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6%80%81%E7%A0%81

    2.3 参数获取方式

    • 使用 Django URL 的正则匹配获取参数
    • url(r'^area/(?P<cityID>\d{6})/$', 'get_area')
      
    • 使用 Django Forms 获取参数

    class FilterForm(forms.Form):
        sys_type = forms.ChoiceField(choices=choices.SYS_CHOICES, required=True, label=u'类型')
    
    def my_view(request):
        form = FilterForm(request.GET)
        if not form.is_valid():
            # 数据不合法
        else:
            # 通过 form.cleaned_data 获取数据
    

    2.4 权限校验

    • 垂直越权 普通用户不允许访问管理员用户资源

    • 平行越权 普通用户不能访问没有授权的其他普通用户资源

    3. 错误码规范

    3.1 错误码设计

    • 合理的设计错误码

    参考设计1

    2000502
    HTTP状态码服务模块代码具体错误代码

    参考设计2

    ERROR_INVALID_FUNCTION ERROR_PATH_NOT_FOUND ERROR_TOO_MANY_OPEN_FILES ERROR_ACCESS_DENIED

    3.2 错误提示应准确并有用

    需要提供两个基本内容:

    • 返回错误状态,解释原因
    • 提示用户如何解决

    例如:

    • 调用 XXX 接口异常,请稍后重试,或联系管理员 XXX
    • 连接 MySQL 数据库异常,请联系管理员 XXX
    • 您输入的 XXX 不符合格式要求,请输入 XXX 格式的数据

    3.3 提供错误说明对照表

    提供一个页面或接口,展示错误码-错误详情的信息。例如:接口 /api/v1/error_code/,返回:

    {
      "http_status_code - error_code - message": [
        [
          412,
          "Error_LOGIN_FRONT_NOT_GIFT",
          "礼品不充足"
        ],
        [
          503,
          "ERROR_FAULT",
          "服务器内部错误"
        ]
      ]
    }
    

    4. 参考