曾海沥 / doc-press · 文件

转到一个项目
api.html 17.9 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>API 交互规范 | 买买买文档平台</title>
    <meta name="generator" content="VuePress 1.7.1">
    
    <meta name="description" content="买买买文档平台">
    
    <link rel="preload" href="/assets/css/0.styles.d07e157f.css" as="style"><link rel="preload" href="/assets/js/app.9f046945.js" as="script"><link rel="preload" href="/assets/js/2.ef86ff21.js" as="script"><link rel="preload" href="/assets/js/13.e003b70f.js" as="script"><link rel="prefetch" href="/assets/js/10.5819cc99.js"><link rel="prefetch" href="/assets/js/11.fd597b20.js"><link rel="prefetch" href="/assets/js/12.b2402a37.js"><link rel="prefetch" href="/assets/js/14.00c355b3.js"><link rel="prefetch" href="/assets/js/15.5f87eecb.js"><link rel="prefetch" href="/assets/js/16.1b53dc86.js"><link rel="prefetch" href="/assets/js/17.ab400218.js"><link rel="prefetch" href="/assets/js/18.20932e4d.js"><link rel="prefetch" href="/assets/js/19.af979abe.js"><link rel="prefetch" href="/assets/js/20.ecc32992.js"><link rel="prefetch" href="/assets/js/21.86007ef2.js"><link rel="prefetch" href="/assets/js/22.8eb68f06.js"><link rel="prefetch" href="/assets/js/23.f9d43b92.js"><link rel="prefetch" href="/assets/js/24.45b4a9ea.js"><link rel="prefetch" href="/assets/js/25.0458cf97.js"><link rel="prefetch" href="/assets/js/26.28900d1b.js"><link rel="prefetch" href="/assets/js/27.81d86e4f.js"><link rel="prefetch" href="/assets/js/28.1807ea10.js"><link rel="prefetch" href="/assets/js/29.c674570a.js"><link rel="prefetch" href="/assets/js/3.3e1e6257.js"><link rel="prefetch" href="/assets/js/30.d9de9467.js"><link rel="prefetch" href="/assets/js/31.c5b3b33e.js"><link rel="prefetch" href="/assets/js/32.267ac0e0.js"><link rel="prefetch" href="/assets/js/4.cbe5fc7a.js"><link rel="prefetch" href="/assets/js/5.6a270bea.js"><link rel="prefetch" href="/assets/js/6.f72612cc.js"><link rel="prefetch" href="/assets/js/7.94e920fe.js"><link rel="prefetch" href="/assets/js/8.b7861e0c.js"><link rel="prefetch" href="/assets/js/9.e023b86e.js">
    <link rel="stylesheet" href="/assets/css/0.styles.d07e157f.css">
  </head>
  <body>
    <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/" class="home-link router-link-active"><img src="/logo.png" alt="买买买文档平台" class="logo"> <span class="site-name can-hide">买买买文档平台</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/" class="nav-link">
  查询导览
</a></div><div class="nav-item"><a href="/product/" class="nav-link">
  项目清单
</a></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="团队文档" class="dropdown-title"><span class="title">团队文档</span> <span class="arrow down"></span></button> <button type="button" aria-label="团队文档" class="mobile-dropdown-title"><span class="title">团队文档</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/team/design/" class="nav-link">
  产品设计
</a></li><li class="dropdown-item"><!----> <a href="/team/ios/" class="nav-link">
  IOS
</a></li><li class="dropdown-item"><!----> <a href="/team/android/" class="nav-link">
  安卓
</a></li><li class="dropdown-item"><!----> <a href="/team/backend/" class="nav-link">
  服务端
</a></li><li class="dropdown-item"><!----> <a href="/team/quality/" class="nav-link">
  测试
</a></li><li class="dropdown-item"><h4>
          前端
        </h4> <ul class="dropdown-subitem-wrapper"><li class="dropdown-subitem"><a href="/team/frontend/overview/" class="nav-link">
  概况
</a></li><li class="dropdown-subitem"><a href="/team/frontend/plugins/" class="nav-link">
  插件库
</a></li><li class="dropdown-subitem"><a href="/team/frontend/utils/" class="nav-link">
  工具集
</a></li></ul></li></ul></div></div><div class="nav-item"><a href="/standard/" class="nav-link router-link-active">
  标准与规范
</a></div><div class="nav-item"><a href="/project/" class="nav-link">
  项目管控
</a></div><div class="nav-item"><a href="/adm/" class="nav-link">
  行政管理
</a></div><div class="nav-item"><a href="/util/" class="nav-link">
  协作工具
</a></div><div class="nav-item"><a href="/guide/" class="nav-link">
  文档写作平台入门
</a></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/" class="nav-link">
  查询导览
</a></div><div class="nav-item"><a href="/product/" class="nav-link">
  项目清单
</a></div><div class="nav-item"><div class="dropdown-wrapper"><button type="button" aria-label="团队文档" class="dropdown-title"><span class="title">团队文档</span> <span class="arrow down"></span></button> <button type="button" aria-label="团队文档" class="mobile-dropdown-title"><span class="title">团队文档</span> <span class="arrow right"></span></button> <ul class="nav-dropdown" style="display:none;"><li class="dropdown-item"><!----> <a href="/team/design/" class="nav-link">
  产品设计
</a></li><li class="dropdown-item"><!----> <a href="/team/ios/" class="nav-link">
  IOS
</a></li><li class="dropdown-item"><!----> <a href="/team/android/" class="nav-link">
  安卓
</a></li><li class="dropdown-item"><!----> <a href="/team/backend/" class="nav-link">
  服务端
</a></li><li class="dropdown-item"><!----> <a href="/team/quality/" class="nav-link">
  测试
</a></li><li class="dropdown-item"><h4>
          前端
        </h4> <ul class="dropdown-subitem-wrapper"><li class="dropdown-subitem"><a href="/team/frontend/overview/" class="nav-link">
  概况
</a></li><li class="dropdown-subitem"><a href="/team/frontend/plugins/" class="nav-link">
  插件库
</a></li><li class="dropdown-subitem"><a href="/team/frontend/utils/" class="nav-link">
  工具集
</a></li></ul></li></ul></div></div><div class="nav-item"><a href="/standard/" class="nav-link router-link-active">
  标准与规范
</a></div><div class="nav-item"><a href="/project/" class="nav-link">
  项目管控
</a></div><div class="nav-item"><a href="/adm/" class="nav-link">
  行政管理
</a></div><div class="nav-item"><a href="/util/" class="nav-link">
  协作工具
</a></div><div class="nav-item"><a href="/guide/" class="nav-link">
  文档写作平台入门
</a></div> <!----></nav>  <ul class="sidebar-links"><li><a href="/standard/" aria-current="page" class="sidebar-link">标准与规范</a></li><li><a href="/standard/git.html" class="sidebar-link">Git 使用规范</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/standard/git.html#git-分支与-ci-cd" class="sidebar-link">Git 分支与 CI/CD</a></li><li class="sidebar-sub-header"><a href="/standard/git.html#分支管理" class="sidebar-link">分支管理</a></li></ul></li><li><a href="/standard/api.html" aria-current="page" class="active sidebar-link">API 交互规范</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/standard/api.html#协议" class="sidebar-link">协议</a></li><li class="sidebar-sub-header"><a href="/standard/api.html#版本" class="sidebar-link">版本</a></li><li class="sidebar-sub-header"><a href="/standard/api.html#接口路径" class="sidebar-link">接口路径</a></li><li class="sidebar-sub-header"><a href="/standard/api.html#http-动作" class="sidebar-link">HTTP 动作</a></li><li class="sidebar-sub-header"><a href="/standard/api.html#数据返回" class="sidebar-link">数据返回</a></li></ul></li><li><a href="/standard/graphql.html" class="sidebar-link">GraphQL API 查询服务</a></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="api-交互规范"><a href="#api-交互规范" class="header-anchor">#</a> API 交互规范</h1> <p>对于数据请求的 API 数据接口，将使用 <code>RESTful API</code> 风格作为团队间数据交互的规范</p> <h2 id="协议"><a href="#协议" class="header-anchor">#</a> 协议</h2> <p>对于生产环境与测试环境，应总是使用 <code>https</code> 协议，开发环境则视方便情况而定</p> <h2 id="版本"><a href="#版本" class="header-anchor">#</a> 版本</h2> <p>应在 URL 中预留版本号，以方便后续因大版本升级需要保留旧版本接口的情况下增加新版本接口的场景</p> <blockquote><p>https://api.maimaimai.com<strong style="color:red;">/v1</strong>/user/list</p></blockquote> <h2 id="接口路径"><a href="#接口路径" class="header-anchor">#</a> 接口路径</h2> <p>对于接口路径的设置，建议使用模块上下级关系进行联合描述，一来模块清晰，二来可读性佳；另外，对于使用的英文单词应使用全小写模式，有词组的情况下，使用 <code>-</code> 隔开，详细的规则可参考：<a href="/team/frontend/overview/standard.html#路由命名规则">路由命名规则</a></p> <div class="language-js line-numbers-mode"><pre class="language-js"><code>https<span class="token operator">:</span><span class="token operator">/</span><span class="token operator">/</span>api<span class="token punctuation">.</span>maimaimai<span class="token punctuation">.</span>com<span class="token operator">/</span>v1<span class="token operator">/</span>system<span class="token operator">/</span>user<span class="token operator">/</span>role<span class="token operator">-</span>auth
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br></div></div><p>上例指定了 <code>系统管理 -&gt; 用户管理 -&gt; 角色授权管理</code> 的列表接口</p> <h2 id="http-动作"><a href="#http-动作" class="header-anchor">#</a> HTTP 动作</h2> <p>对于 <code>RESTful API</code> 风格的应用，很重要的部分是使用 http 标准动词对操作类型进行描述，所以在定义 url 时不能有动词内容</p> <p>对于资源的具体操作类型，由 <strong>HTTP</strong> 动词表示。常用的 <strong>HTTP</strong> 动词有下面五个（括号里是对应的 <strong>SQL</strong> 命令）</p> <ul><li>GET（SELECT）：从服务器取出资源（一项或多项）。</li> <li>POST（CREATE）：在服务器新建一个资源。</li> <li>PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。</li> <li>PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。</li> <li>DELETE（DELETE）：从服务器删除资源。</li></ul> <p>实际应用场景示例</p> <table><thead><tr><th>URL 示例</th> <th>HTTP 动词类型</th> <th>描述</th></tr></thead> <tbody><tr><td>/system/user</td> <td>GET</td> <td>获得用户列表（数据表格）</td></tr> <tr><td>/system/user/:id</td> <td>GET</td> <td>获得单个用户明细数据</td></tr> <tr><td>/system/user</td> <td>POST</td> <td>新增用户</td></tr> <tr><td>/system/user</td> <td>PUT</td> <td>修改用户</td></tr> <tr><td>/system/user/:id</td> <td>DELETE</td> <td>删除用户</td></tr></tbody></table> <h2 id="数据返回"><a href="#数据返回" class="header-anchor">#</a> 数据返回</h2> <p>根据不同的操作类型，返回的数据格式应符合以下规范</p> <blockquote><p>数据交互的基础模型以及数据表格数据结构请参考：<a href="/team/frontend/overview/http.html">数据交互格式标准</a></p></blockquote> <p>GET <code>/system/user</code> 返回数据表格</p> <div class="language-js line-numbers-mode"><pre class="language-js"><code><span class="token punctuation">{</span>
  code<span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
  msg<span class="token operator">:</span> <span class="token string">'ok'</span><span class="token punctuation">,</span>
  data<span class="token operator">:</span> <span class="token punctuation">{</span>
    grid<span class="token operator">:</span> <span class="token punctuation">{</span>
      totalRow<span class="token operator">:</span> <span class="token number">10</span><span class="token punctuation">,</span>
      list<span class="token operator">:</span> <span class="token punctuation">[</span><span class="token operator">...</span><span class="token punctuation">]</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br></div></div><p>GET <code>/system/user/:id</code> 返回相关数据模型</p> <div class="language-js line-numbers-mode"><pre class="language-js"><code><span class="token punctuation">{</span>
  code<span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
  msg<span class="token operator">:</span> <span class="token string">'ok'</span><span class="token punctuation">,</span>
  data<span class="token operator">:</span> <span class="token punctuation">{</span> object <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br></div></div><p>POST <code>/system/user</code> 新增数据</p> <div class="language-js line-numbers-mode"><pre class="language-js"><code><span class="token punctuation">{</span>
  code<span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
  msg<span class="token operator">:</span> <span class="token string">'ok'</span><span class="token punctuation">,</span>
  data<span class="token operator">:</span> <span class="token punctuation">{</span> object <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br></div></div><p>新增业务数据的场景下，应将保存成功的数据进行返回，以满足部分业务需要在数据保存成功后提取相应数据字段进行后续操作，例如数据表单的数据，需要依次保存在 A 和 B 两个业务模块中，需要在 A 模块保存完成后，获得 <code>A.id</code> 并提供给 B 模块作为 <code>B.aId</code> 进行保存</p> <p>PUT <code>/system/user</code> 更新数据</p> <div class="language-js line-numbers-mode"><pre class="language-js"><code><span class="token punctuation">{</span>
  code<span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
  msg<span class="token operator">:</span> <span class="token string">'ok'</span><span class="token punctuation">,</span>
  data<span class="token operator">:</span> <span class="token punctuation">{</span> object <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br></div></div><p>更新业务数据的场景，同样返回该操作保存成功后的完整数据内容，应用场景类似于上述的新增业务场景</p> <p>DELETE <code>/system/user/:id</code> 删除数据</p> <div class="language-js line-numbers-mode"><pre class="language-js"><code><span class="token punctuation">{</span>
  code<span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
  msg<span class="token operator">:</span> <span class="token string">'ok'</span><span class="token punctuation">,</span>
  data<span class="token operator">:</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre> <div class="line-numbers-wrapper"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br></div></div><p>删除成功，数据内容返回空即可；失败则使用常规错误模式输出相关信息</p></div> <footer class="page-edit"><!----> <div class="last-updated"><span class="prefix">最后更新时间:</span> <span class="time">10/15/2020, 7:03:30 AM</span></div></footer> <div class="page-nav"><p class="inner"><span class="prev">
      ←
      <a href="/standard/git.html" class="prev">
        Git 使用规范
      </a></span> <span class="next"><a href="/standard/graphql.html">
        GraphQL API 查询服务
      </a>
      →
    </span></p></div> </main></div><div class="global-ui"><!----></div></div>
    <script src="/assets/js/app.9f046945.js" defer></script><script src="/assets/js/2.ef86ff21.js" defer></script><script src="/assets/js/13.e003b70f.js" defer></script>
  </body>
</html>