(window.webpackJsonp=window.webpackJsonp||[]).push([[13],{588:function(s,t,a){"use strict";a.r(t);var n=a(27),e=Object(n.a)({},(function(){var s=this,t=s.$createElement,a=s._self._c||t;return a("ContentSlotsDistributor",{attrs:{"slot-key":s.$parent.slotKey}},[a("h1",{attrs:{id:"api-交互规范"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#api-交互规范"}},[s._v("#")]),s._v(" API 交互规范")]),s._v(" "),a("p",[s._v("对于数据请求的 API 数据接口，将使用 "),a("code",[s._v("RESTful API")]),s._v(" 风格作为团队间数据交互的规范")]),s._v(" "),a("h2",{attrs:{id:"协议"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#协议"}},[s._v("#")]),s._v(" 协议")]),s._v(" "),a("p",[s._v("对于生产环境与测试环境，应总是使用 "),a("code",[s._v("https")]),s._v(" 协议，开发环境则视方便情况而定")]),s._v(" "),a("h2",{attrs:{id:"版本"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#版本"}},[s._v("#")]),s._v(" 版本")]),s._v(" "),a("p",[s._v("应在 URL 中预留版本号，以方便后续因大版本升级需要保留旧版本接口的情况下增加新版本接口的场景")]),s._v(" "),a("blockquote",[a("p",[s._v("https://api.maimaimai.com"),a("strong",{staticStyle:{color:"red"}},[s._v("/v1")]),s._v("/user/list")])]),s._v(" "),a("h2",{attrs:{id:"接口路径"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#接口路径"}},[s._v("#")]),s._v(" 接口路径")]),s._v(" "),a("p",[s._v("对于接口路径的设置，建议使用模块上下级关系进行联合描述，一来模块清晰，二来可读性佳；另外，对于使用的英文单词应使用全小写模式，有词组的情况下，使用 "),a("code",[s._v("-")]),s._v(" 隔开，详细的规则可参考："),a("RouterLink",{attrs:{to:"/team/frontend/overview/standard.html#路由命名规则"}},[s._v("路由命名规则")])],1),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[s._v("https"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),s._v("api"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(".")]),s._v("maimaimai"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(".")]),s._v("com"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),s._v("v1"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),s._v("system"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),s._v("user"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("/")]),s._v("role"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("-")]),s._v("auth\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br")])]),a("p",[s._v("上例指定了 "),a("code",[s._v("系统管理 -> 用户管理 -> 角色授权管理")]),s._v(" 的列表接口")]),s._v(" "),a("h2",{attrs:{id:"http-动作"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#http-动作"}},[s._v("#")]),s._v(" HTTP 动作")]),s._v(" "),a("p",[s._v("对于 "),a("code",[s._v("RESTful API")]),s._v(" 风格的应用，很重要的部分是使用 http 标准动词对操作类型进行描述，所以在定义 url 时不能有动词内容")]),s._v(" "),a("p",[s._v("对于资源的具体操作类型，由 "),a("strong",[s._v("HTTP")]),s._v(" 动词表示。常用的 "),a("strong",[s._v("HTTP")]),s._v(" 动词有下面五个（括号里是对应的 "),a("strong",[s._v("SQL")]),s._v(" 命令）")]),s._v(" "),a("ul",[a("li",[s._v("GET（SELECT）：从服务器取出资源（一项或多项）。")]),s._v(" "),a("li",[s._v("POST（CREATE）：在服务器新建一个资源。")]),s._v(" "),a("li",[s._v("PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。")]),s._v(" "),a("li",[s._v("PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。")]),s._v(" "),a("li",[s._v("DELETE（DELETE）：从服务器删除资源。")])]),s._v(" "),a("p",[s._v("实际应用场景示例")]),s._v(" "),a("table",[a("thead",[a("tr",[a("th",[s._v("URL 示例")]),s._v(" "),a("th",[s._v("HTTP 动词类型")]),s._v(" "),a("th",[s._v("描述")])])]),s._v(" "),a("tbody",[a("tr",[a("td",[s._v("/system/user")]),s._v(" "),a("td",[s._v("GET")]),s._v(" "),a("td",[s._v("获得用户列表（数据表格）")])]),s._v(" "),a("tr",[a("td",[s._v("/system/user/:id")]),s._v(" "),a("td",[s._v("GET")]),s._v(" "),a("td",[s._v("获得单个用户明细数据")])]),s._v(" "),a("tr",[a("td",[s._v("/system/user")]),s._v(" "),a("td",[s._v("POST")]),s._v(" "),a("td",[s._v("新增用户")])]),s._v(" "),a("tr",[a("td",[s._v("/system/user")]),s._v(" "),a("td",[s._v("PUT")]),s._v(" "),a("td",[s._v("修改用户")])]),s._v(" "),a("tr",[a("td",[s._v("/system/user/:id")]),s._v(" "),a("td",[s._v("DELETE")]),s._v(" "),a("td",[s._v("删除用户")])])])]),s._v(" "),a("h2",{attrs:{id:"数据返回"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#数据返回"}},[s._v("#")]),s._v(" 数据返回")]),s._v(" "),a("p",[s._v("根据不同的操作类型，返回的数据格式应符合以下规范")]),s._v(" "),a("blockquote",[a("p",[s._v("数据交互的基础模型以及数据表格数据结构请参考："),a("RouterLink",{attrs:{to:"/team/frontend/overview/http.html"}},[s._v("数据交互格式标准")])],1)]),s._v(" "),a("p",[s._v("GET "),a("code",[s._v("/system/user")]),s._v(" 返回数据表格")]),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n  code"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  msg"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[s._v("'ok'")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  data"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n    grid"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n      totalRow"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("10")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n      list"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("[")]),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v("...")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("]")]),s._v("\n    "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n  "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br"),a("span",{staticClass:"line-number"},[s._v("2")]),a("br"),a("span",{staticClass:"line-number"},[s._v("3")]),a("br"),a("span",{staticClass:"line-number"},[s._v("4")]),a("br"),a("span",{staticClass:"line-number"},[s._v("5")]),a("br"),a("span",{staticClass:"line-number"},[s._v("6")]),a("br"),a("span",{staticClass:"line-number"},[s._v("7")]),a("br"),a("span",{staticClass:"line-number"},[s._v("8")]),a("br"),a("span",{staticClass:"line-number"},[s._v("9")]),a("br"),a("span",{staticClass:"line-number"},[s._v("10")]),a("br")])]),a("p",[s._v("GET "),a("code",[s._v("/system/user/:id")]),s._v(" 返回相关数据模型")]),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n  code"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  msg"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[s._v("'ok'")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  data"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v(" object "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br"),a("span",{staticClass:"line-number"},[s._v("2")]),a("br"),a("span",{staticClass:"line-number"},[s._v("3")]),a("br"),a("span",{staticClass:"line-number"},[s._v("4")]),a("br"),a("span",{staticClass:"line-number"},[s._v("5")]),a("br")])]),a("p",[s._v("POST "),a("code",[s._v("/system/user")]),s._v(" 新增数据")]),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n  code"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  msg"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[s._v("'ok'")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  data"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v(" object "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br"),a("span",{staticClass:"line-number"},[s._v("2")]),a("br"),a("span",{staticClass:"line-number"},[s._v("3")]),a("br"),a("span",{staticClass:"line-number"},[s._v("4")]),a("br"),a("span",{staticClass:"line-number"},[s._v("5")]),a("br")])]),a("p",[s._v("新增业务数据的场景下，应将保存成功的数据进行返回，以满足部分业务需要在数据保存成功后提取相应数据字段进行后续操作，例如数据表单的数据，需要依次保存在 A 和 B 两个业务模块中，需要在 A 模块保存完成后，获得 "),a("code",[s._v("A.id")]),s._v(" 并提供给 B 模块作为 "),a("code",[s._v("B.aId")]),s._v(" 进行保存")]),s._v(" "),a("p",[s._v("PUT "),a("code",[s._v("/system/user")]),s._v(" 更新数据")]),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n  code"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  msg"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[s._v("'ok'")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  data"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v(" object "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br"),a("span",{staticClass:"line-number"},[s._v("2")]),a("br"),a("span",{staticClass:"line-number"},[s._v("3")]),a("br"),a("span",{staticClass:"line-number"},[s._v("4")]),a("br"),a("span",{staticClass:"line-number"},[s._v("5")]),a("br")])]),a("p",[s._v("更新业务数据的场景，同样返回该操作保存成功后的完整数据内容，应用场景类似于上述的新增业务场景")]),s._v(" "),a("p",[s._v("DELETE "),a("code",[s._v("/system/user/:id")]),s._v(" 删除数据")]),s._v(" "),a("div",{staticClass:"language-js line-numbers-mode"},[a("pre",{pre:!0,attrs:{class:"language-js"}},[a("code",[a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),s._v("\n  code"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token number"}},[s._v("0")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  msg"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[s._v("'ok'")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v(",")]),s._v("\n  data"),a("span",{pre:!0,attrs:{class:"token operator"}},[s._v(":")]),s._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("{")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[s._v("}")]),s._v("\n")])]),s._v(" "),a("div",{staticClass:"line-numbers-wrapper"},[a("span",{staticClass:"line-number"},[s._v("1")]),a("br"),a("span",{staticClass:"line-number"},[s._v("2")]),a("br"),a("span",{staticClass:"line-number"},[s._v("3")]),a("br"),a("span",{staticClass:"line-number"},[s._v("4")]),a("br"),a("span",{staticClass:"line-number"},[s._v("5")]),a("br")])]),a("p",[s._v("删除成功，数据内容返回空即可；失败则使用常规错误模式输出相关信息")])])}),[],!1,null,null,null);t.default=e.exports}}]);