FiData开放平台
页面树结构

版本比较

旧版本 16

changes.mady.by.user 许俊杰

保存于

比较

新版本 当前版本

changes.mady.by.user 李新毅

保存于

标识

  • 该行被添加。
  • 该行被删除。
  • 格式已经改变。

开发文档阅读说明

  1. API接口开放了丰富的接口说明，开发者可以借助接口能力，实现FiData的二次开发，通过目录导航可以快速预览，目录树按功能块聚合归类，如数据接入接口，API网关服务接口等。
  2. 文档的阅读次序，建议先阅读一遍开发指南，并关注如何获取token，然后就可以独立查看各个功能块的API接口文档说明。


一、项目目录简介

二、项目路由管理

三、接口调用流程

请求接口：所有的接口需使用HTTPS/HTTP协议、JSON数据格式、UTF8编码。接口说明格式如下：

常用请求方式：

注：仅对部分重点目录进行介绍。在本文档后续的介绍过程中，约定始终位于项目根目录(./)

./src——项目最重要的文件夹，代码及图片资源等都位于本文件夹

  • ./src/api——存放不同功能模块的请求接口
  • ./src/assets——静态资源文件夹，存放图片及字体资源
  • ./src/components——跨模块组件的存放位置（如：数据接入及数仓建模同时使用了 Example.vue 组件，则将 Example.vue 文件存入本文件夹）
  • ./src/icons——svg图标存放位置
  • ./src/layout——项目布局组件的存放位置，例如侧边栏组件及导航条组件等
  • ./src/mixin——跨模块组件的混入代码内容
  • ./src/router——动态路由及静态路由的配置文件存放位置
  • ./src/store——vuex状态管理文件的存放位置。注：本项目已对./src/modules文件夹做出批量化导入处理。
  • ./src/styles——全局样式文件及跨模块样式文件的存放位置
  • ./src/utils——工具类及对axios进行封装的文件的存放位置。注：不同模块的axios封装处理不同，因此产生了多个封装文件
  • ./src/views——项目组件文件的存放位置


二、项目路由管理

  1. 动态路由管理：

    • 本项目的路由文件位于 ./src/router/index.js。在 index.js 文件中，componentMap 为动态路由对象，若需要在导航菜单中额外添加项目，则在 componentMap 对象中新增菜单属性，并懒加载导入菜单指向的文件地址即可。例如：example: () => import('example.vue的地址')，另外，新增的菜单需要在“权限配置-服务授权”中设置角色权限方可访问。

  2. 静态路由管理：

    • 同样是 ./src/router/index.js 文件，该文件中的 constantRoutes 为静态路由数组，登陆页路由、首页路由、404页面路由等都位于本数组中，若需要在项目中添加额外的静态路由，仿照数组中已存在的元素对象进行新建即可。


三、接口调用流程

接口调用流程梗概图：

Image Added

  1. 请求方式及请求地址

    1. 本项目的常用请求方式有4种：GET/POST/PUT/
DELETE（HTTP） 请求地址：http
    1. DELETE（http协议）；
    2. 除登录接口及获取项目标题的接口之外，本项目所有接口均需要token；
    3. 请求地址：http://
10.220.108.140
    1. XXXXX:41004/
（注：请求的api地址及端口号配置于项目根目录下的.env.pudong文件）
详细请求方式请查看“接口文档”中的示例1) 请求方式，标明接口调用的HTTP方法，区分HttpGet/HttpPost请求。所有的请求都为http/https协议。
2) 请求地址，参数中标注大写的单词，表示为需要替换的变量。在上面的例子中 ID 及 SECRET 为需要替换的变量，根据实际获取值更新。假如，这里我们获取到的ID=wwabcddzxdkrsdv，SECRET=vQT_03RDVA3uE6JDASDASDAiXUvccqV8mDgLdLI，那么上述的请求在发送时为：
https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwabcddzxdkrsdv&corpsecret=vQT_03RDVA3uE6JDASDASDAiXUvccqV8mDgLdLI
3) 请求包体/参数说明，标明请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考该定义范围。
4) 权限说明，标明接口的使用范围，开发者应特别留意调用场景。比如，同步通讯录的接口必须要用通讯录同步助手的access_token，发送消息指定的范围必须是应用可见范围内的结点等。
5) 返回结果/参数说明，标明返回参数示例及说明。特别留意，所有接口在调用失败时返回包里都有errcode、errmsg（部分接口在调用成功时没有返回errcode和errmsg）。开发者需根据errcode存在且不为0判断为失败，否则为成功（errcode意义请见全局错误码）。而errmsg仅作参考，后续可能会有变动，因此不可作为是否调用成功的判据。

Image Removed

  1. 获取access_token，参考 文档说明。
  2. 缓存和刷新access_token。
    开发者需要缓存access_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access_token失效或过期时，需要重新获取。
  3. 调用具体的业务接口

四、组件数据流转

五、基本调试方法

可以使用Postman等工具排查问题原因。

    1. （注：各个环境的网关地址）

  2. 封装axios

    1. 对axios的封装文件位于 ./src/utils 目录下，一般的命名规则为 “xxxRequest.js”。
    2. 不同模块有不同的封装文件。

  3. 获取token

    1. 本项目的前端采用了“js-cookie”库操作cookie，当登录成功后，后端会将token返回到前端，此时前端会将token传入cookie中。设置及获取token的代码详见 ./src/utils/auth.js 文件。
    2. 通过导入 ./src/utils/auth.js 文件，即可使用 getToken() 方法获取token

  4. 请求拦截及响应拦截

    1. 封装文件中编写了请求拦截及响应拦截代码段，可给每个请求附加 token，并对响应结果做出预先处理

  5. 在具体的api文件中引入封装好的axios文件

    1. api接口文件只需要引入该模块的封装好的axios文件，并以导出函数的形式对外暴露接口即可；
    2. api接口文件中的函数内容相对固定，函数内仅需要返回一个axios封装方法，并在方法中传入url、methods、data(可选)等配置项即可

  6. api文件导出api接口

    1. 在组件文件中，只需要导入api文件中的函数，即可调用接口

  7. 请求状态判断及响应数据获取

    1. 请求状态码详情参考百度百科：https://baike.baidu.com/item/HTTP/243074?fr=aladdin 
    2. 如果请求成功，则后端会返回固定格式的响应数据，其中：code 表示响应状态，code为0时表示响应正常，非0则表示响应异常，code可作为调用是否成功的判断依据；msg表示响应语句；data表示响应的数据

  8. 具体的请求案例请查看“API接口文档”


四、组件数据流转

本项目采用Vue框架进行开发，因此在项目中，组件间的数据传输方式大致有以下几种：

  1. 父子组件间：props & emit

    1. 父组件在子组件标签中添加要传输的数据属性，子组件采用 props 配置项进行接收；子组件采用 emit，触发父组件的自定义请求方法

  2. 任意组件间：Bus

    1. Bus是发布订阅模式的运用，利用vue的自定义事件机制，在触发的地方通过emit向外发布一个事件，在需要监听的页面，通过on监听事件

  3. 任意组件间：Vuex

    1. Vuex 是一个专为 Vue.js 应用程序开发的状态管理模式 + 库。它采用集中式存储管理应用的所有组件的状态，并以相应的规则保证状态以一种可预测的方式发生变化


五、基本调试方法

可以使用Postman等工具排查问题原因。


六、注意事项

更改页面时请勿在原文件内修改，而应新建一个同名文件，并附带版本号，版本号和文件名之间用短横线“-”分割。例如：Example-v2.0.vue