今日投资API规范 2023 ​

版本 ​

V2023

适用 ​

spring-cloud-investoday-starter 2.7.X及以上版本

URL ​

• 字母全小写

• 如果有两个单词组成时，采用中划线(-)隔开

  在搜索引擎中，把中划线当做空格处理，而下划线是被忽略的。使用中划线是对搜索引擎友好的写法

// good
api-spec、keep-limit、week-report

// bad
apiSpec、keepLimit

// good
api-spec、keep-limit、week-report

// bad
apiSpec、keepLimit

• path采用复数名词而非动词

// good
/articles

// bad
/article/list

// good
/articles

// bad
/article/list

• 文件名及目录名要具描述性，层级尽量少，不能超过三层

参数 ​

• 不使用path传参，只通过 Query 或者 Body 传参

• 没有大参数传递的要求，一般不使用 Post 方式

• Post方式可以同时传递 Body 和 Query，不一定都放入Body中

• 涉及序列传递（如股票代码序列）时，考虑使用 Post 方式

Header ​

• GET 请求一律采用 application/x-www-form-urlencoded; charset=utf-8

• POST 请求一律采用 application/json; charset=utf-8

• PUT 请求一律采用 application/json; charset=utf-8

• DELETE 请求一律采用 application/json; charset=utf-8

• PATCH 请求一律采用 **application/**json-patch+json; charset=utf-8

响应 ​

正常返回值 ​

• 所有返回值都是JSON对象，如果返回值是List，会被包裹在data属性中

  其中 requestId 存在即显示，apiVersion 非最新规范时才显示

  json

  // Object类型
  {
    code: "SUCCESS",
    requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
    apiVersion: "V2023",
    data:{
      username: "name",
    	age: 10
    }
  }
  
  // Array类型
  {
     code: "SUCCESS",
     requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
     apiVersion: "V2023",
     data: [{
       	username: "name",
    		age: 10
     },{
       	username: "name2",
    		age: 12
     }]
  }
  
  // PageHelper对象
  {
    code: "SUCCESS",
    requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
    apiVersion: "V2023",
    data: [{
       	username: "name",
    		age: 10
     },{
       	username: "name2",
    		age: 12
     }],
    total: 0,
    pageNum: 0,
    size: 0
  }

  // Object类型
  {
    code: "SUCCESS",
    requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
    apiVersion: "V2023",
    data:{
      username: "name",
    	age: 10
    }
  }
  
  // Array类型
  {
     code: "SUCCESS",
     requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
     apiVersion: "V2023",
     data: [{
       	username: "name",
    		age: 10
     },{
       	username: "name2",
    		age: 12
     }]
  }
  
  // PageHelper对象
  {
    code: "SUCCESS",
    requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
    apiVersion: "V2023",
    data: [{
       	username: "name",
    		age: 10
     },{
       	username: "name2",
    		age: 12
     }],
    total: 0,
    pageNum: 0,
    size: 0
  }

• 所有属性包括嵌入属性都采用首字母小写的驼峰格式

• 所有返回值对象都包括RequestID属性

• 注意所有返回值对象都是原始返回，切记不要包装

• 所有HTTP请求码都是2XX

错误返回值 ​

// 业务级
{
  requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
  code: "SignatureDoesNotMatch",
  message: "签名不匹配"
}

// 系统级
{
    "path": "/test/e",
    "requestId": "CE8E2845-3B01-4F20-8D8A-5FAD0D3E8B7A",
    "message": null,
    "stackTrace": null,
    "cause": null,
    "code": "NullPointerException",
    "exception": "java.lang.NullPointerException"
}

// 业务级
{
  requestId: "1E7C726B-AFC5-4BF9-8F1B-25DEC8118963",
  code: "SignatureDoesNotMatch",
  message: "签名不匹配"
}

// 系统级
{
    "path": "/test/e",
    "requestId": "CE8E2845-3B01-4F20-8D8A-5FAD0D3E8B7A",
    "message": null,
    "stackTrace": null,
    "cause": null,
    "code": "NullPointerException",
    "exception": "java.lang.NullPointerException"
}

• code: 错误码，一律采用英文，主要用于机器识别码；可以采用一级或二级码，例如：invalidDatabaseName.duplicate 表示指定的数据库名已存在
• message: 错误信息。主要服务于开发人员识别解释
• requestId: 目前用大写UUID，主要用于跟踪错误信息

状态码 ​

• 2XX---正常返回码，表示请求按照预期执行并成功返回了信息。服务端要尽可能给用户返回这种结果。

• • 200 O****K – [GET]---客户端向服务器请求数据时，服务器找到这些数据并将之返回给客户端（此行为幂等）[GET操作只能获取数据（即只读），不应该对服务器的数据进行任何形式的修改]
  • 201 CREATED – [POST/PUT/PATCH]---客户端向服务器发送数据，服务器为这些数据创建一个资源
  • 204 NO CONTENT – [DELETE]---客户端请求服务器删除一个资源时，服务器将该资源删除

• 4XX---错误返回码，主要表示由客户端引起的错误，例如请求参数错误或者访问一个不存在的资源，这些必须为幂等操作，并且不能改变服务器的状态。

• • 400 Invalid Request**– [POST/PUT/PATCH]**---客户端给服务器发送了一个无效的请求，服务器对此不作任何动作（此行为幂等）。
  • 401 Unauthorized**– [*]****---**-认证未通过的请求。
  • 402 Payment Required – [*]****----需要先支付的请求。
  • 403 Forbidden**– [*]****---**-客户端请求的资源不可用。服务器理解客户的请求，但拒绝处理它，通常由于服务器文件或目录的权限设置导致的WEB访问错误。
  • 404 Not Found – [*]---客户端请求的资源或资源集合不存在，服务端对此不作任何动作（此行为幂等）
  • 405 Method Not Allowed**---**表示请求的方法不允许。
  • 406 Not Acceptable**---**请求头的Accept的内容特性与后台的响应实体Content-Type不一致。还包括字符集、编码、语言、范围等的某一个不一致。
  • 407 Proxy Authentication Required**---**要求代理身份验证。与401响应类似，您必须首先登录（输入用户名和密码）代理服务器。代理服务器必须返回一个 Proxy-Authenticate 信息头用以客户端进行验证。
  • 408 Request Timeout**---**客户端请求超时。
  • 409 Conflict**---**由于和被请求的资源的当前状态（版本）之间存在冲突，请求无法完成。这个代码只允许在：用户被认为能够解决冲突，并且会重新提交新的请求。该响应应当包含足够的信息以便用户发现冲突的源头。冲突通常发生于对 PUT 请求的处理中。例如，在采用版本检查的环境下，某次 PUT 提交的对特定资源的修改请求所附带的版本信息与之前的某个（第三方）请求相冲突，那么此时服务器就应该返回一个409错误，告知用户请求无法完成。此时，响应实体中很可能会包含两个冲突版本之间的差异比较，以便用户重新提交归并以后的新版本。（较少见）
  • 410 Gone**---**通知用户该资源已经永远不再可用，并且服务器拥有者希望所有指向这个资源的远端连接也被删除。这类事件在限时、增值服务中很普遍。
  • **411 Length Required---**表示请求头没有定义 Content-Length。（较少见）
  • **412 Precondition Failed---**服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。这个状态码允许客户端在获取资源时在请求的元信息（请求头字段数据）中设置先决条件，以此避免该请求方法被应用到其希望的内容以外的资源上。（较少见）
  • 413 Request Entity Too Large---请求实体太大。此种情况下，服务器可以关闭连接以免客户端继续发送此请求。如果这个状况是临时的，服务器应当返回一个 Retry-After 的响应头，以告知客户端可以在多少时间以后重新尝试。（上传文件是用到，较少见）
  • **414 Request-URI Too Long---**请求URI 过长。通常的情况包括：本应使用POST方法的表单提交变成了GET方法，导致查询字符串（Query String）过长。重定向URI “黑洞”，例如每次重定向把旧的 URI 作为新的 URI 的一部分，导致在若干次重定向后 URI 超长。（较少见）
  • **415 Unsupported Media Type---**对于当前请求的方法和所请求的资源，请求中提交的实体并不是服务器中所支持的格式，因此请求被拒绝。（较少见）
  • **416 Requested Range not satisfiable---**所请求的范围无法满足。客户端发送的 HTTP 数据流包含一个“范围”请求头，规定了一个后台无法满足的字节范围。（较少见）
  • **417 Expectation Failed---**预期结果失败。客户端发送的 HTTP 数据流含有一个无法满足的“预期”请求。该预期请求是相当一般化的，即在 HTTP 协议中只有松散的定义。 它可以指定一个以上的预期值， 不同的 Web 服务器可能对各个预期值可出不同的解释。（较少见）
  • 418 **I AM A Teapot---**我是茶壶不是服务器。一般用作愚人节、复活节彩蛋。（较少见）
  • **422 Unprocessable Entity---**请求格式错误，但出现了语义错误，以至于服务端无法响应。可以理解为服务端能理解请求资源类型 content-type，否则应该返回 415（Unsupported Media Type），也能理解请求实体内容，否则应该返回 400（Bad Request）。（RFC 4918 WebDAV）（较少见）
  • **423 Locked---**当前资源被锁定。（RFC 4918 WebDAV）（较少见）
  • **424 Failed Dependency---**由于之前的某个请求发生的错误，导致当前请求失败，例如 PROPPATCH。（RFC 4918 WebDAV）（较少见）
  • **426 Upgrade Required---**客户端应当切换到TLS/1.0，更新协议。（较少见）
  • **428 Precondition Required---**客户端发送 HTTP 请求时，必须要满足的一些预设条件。例如 If-None-Match 头，经常用在 GET 请求中。如果指定了 If-None-Match ，那么客户端只在响应中的 ETag 改变后才会重新接受回应。另外一个例子是 If-Match 头，一般用在 PUT 请求上，用于指示只更新但没有被改变的资源。这在多个客户端使用 HTTP 服务时用来防止彼此间覆盖相同内容的情况。这个方法为服务器提供一种有效的方法来阻止 “lost update”问题的出现。
  • 429 Too Many Requests**---**太多请求。当你需要限制客户端请求某个服务的数量，也就是限制请求速度时，该状态码就会非常有用。同时包含一个 Retry-After 响应头告诉客户端多久后可以再次请求服务。
  • 431 **Request Header Fields Too Large--**请求头字段太大。这个错误不应该发生在经过良好测试的生产系统上，但在测试新系统时可以更频繁地发现。

状态码参考 ​