Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
799 lines (563 sloc) 22.7 KB

蓝眼云盘api接口

一、实体

在详细介绍各controller中的接口前,有必要先介绍蓝眼云盘中的各实体,所有的实体基类均为Base

Base

Base定义如下,所有会在数据库中持久化的实体均会继承BaseController在返回实体给前端时,会将字段和值序列化成json字符串,其中键就和每个实体字段后面的json标签一致,下文也会有详细例子介绍

type Base struct {
    //唯一标识
	Uuid       string    `gorm:"primary_key" json:"uuid"`
	//排序用的字段,一般是时间戳来表示序号先后
	Sort       int64     `json:"sort"`
	//修改时间
	ModifyTime time.Time `json:"modifyTime"`
	//创建时间
	CreateTime time.Time `json:"createTime"`
}

Preference

Preference是整个网站的偏好设置,网站的名称,logo,favicon,版权,备案号等信息均由这个实体负责。定义如下:

type Preference struct {
    //继承Base,也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//网站名称
	Name        string `json:"name"`
	//网站的logo url
	LogoUrl     string `json:"logoUrl"`
	//网站的favicon.ico url
	FaviconUrl  string `json:"faviconUrl"`
	//网站下方第一行信息,一般是版权信息
	FooterLine1 string `json:"footerLine1"`
	//网站下方的第二行信息,一般是本案信息
	FooterLine2 string `json:"footerLine2"`
	//当前运行的蓝眼博客版本,这个字段不可修改,每次发版时硬编码
	Version     string `json:"version"`
}

Matter

Matter是代表文件(文件夹是一种特殊的文件),为了和系统的file重复,这里使用matter,这个实体是蓝眼云盘最重要的实体:

type Matter struct {
    //继承Base,也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//所在的文件夹的uuid,如果在根目录下,这个字段为 root
	Puuid    string  `json:"puuid"`
	//创建这个文件的用户uuid
	UserUuid string  `json:"userUuid"`
	//该文件是否是文件夹
	Dir      bool    `json:"dir"`
	//该文件是否是应用文件,比如用户上传的头像这个字段就为true. 一般上传的文件就为false
	Alien    bool    `json:"alien"`
	//文件名,带后缀名。例如:avatar.jpg
	Name     string  `json:"name"`
    //文件的md5值,目前该功能尚未实现,作为保留字段
	Md5      string  `json:"md5"`
	//文件大小,单位 byte。比如某个文件1M大,那么这里就为: 1048576
	Size     int64   `json:"size"`
	//文件是否为私有,如果true则该文件只能作者或超级管理员可以下载,如果false所有人均可以通过下载链接下载。
	Privacy  bool    `json:"privacy"`
	//文件在磁盘中的路径,前端无需关心这个字段。但是后端在寻找文件时这个字段非常关键。
	Path     string  `json:"path"`
	//该文件的父级matter,该字段不会持久化到数据集,属于获取matter详情时临时组装出来的。
	Parent   *Matter `gorm:"-" json:"parent"`
}

User

User是代表用户:

type User struct {
    //继承Base,也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//角色,有以下枚举值:GUEST(游客,不会持久化到数据库),USER(普通用户),ADMINISTRATOR(超级管理员)
	Role      string    `json:"role"`
	//用户名,在Matter的path字段中很有用。
	Username  string    `json:"username"`
	//密码,默认不会返回给前端
	Password  string    `json:"-"`
	//邮箱,作为登录时的账户
	Email     string    `json:"email"`
	//手机
	Phone     string    `json:"phone"`
	//性别,有以下枚举值:MALE(男性),FEMALE(女性),UNKNOWN(未知)
	Gender    string    `json:"gender"`
	//城市
	City      string    `json:"city"`
	//头像Url
	AvatarUrl string    `json:"avatarUrl"`
	//上次登录时的ip
	LastIp    string    `json:"lastIp"`
	//上次登录的时间
	LastTime  time.Time `json:"lastTime"`
	//该用户允许上传的单文件最大大小
	SizeLimit int64     `json:"sizeLimit"`
	//状态,有以下枚举值:OK(正常),DISABLED(被禁用)
	Status    string    `json:"status"`
}

UploadToken

用于给陌生人上传的token

type UploadToken struct {
    //继承Base,也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//颁发该token的用户,系统中任何用户都能颁发token
	UserUuid   string    `json:"userUuid"`
	//使用这个token上传文件就必须上传在这个文件夹下
	FolderUuid string    `json:"folderUuid"`
	//陌生人上传好了的文件uuid
	MatterUuid string    `json:"matterUuid"`
	//过期时间
	ExpireTime time.Time `json:"expireTime"`
	//使用这个token上传文件就必须是这个文件名
	Filename   string    `json:"filename"`
	//使用这个token上传文件就必须是这个公私有性
	Privacy    bool      `json:"privacy"`
	//使用这个token上传文件就必须这个大小
	Size       int64     `json:"size"`
	//使用这个token上传文件陌生人的ip
	Ip         string    `json:"ip"`
}

DownloadToken

用于给陌生人下载的token,一个matter如果Privacy=true,那么就意味着只有自己或者超级管理员可以下载,如果让某些自己信任的用户也能下载,那么就需要生成DownloadToken给这些用户来下载。

type DownloadToken struct {
    //继承Base,也就是说Base中的Uuid,Sort,ModifyTime,CreateTime这里也会有
	Base
	//颁发该token的用户
	UserUuid   string    `json:"userUuid"`
	//该token只能下载这个文件
	MatterUuid string    `json:"matterUuid"`
	//有效期截止
	ExpireTime time.Time `json:"expireTime"`
	//下载者的ip
	Ip         string    `json:"ip"`
}

Pager

在前端请求一个列表时,通常返回的都是一个PagerPager中就是装的各个实体的列表。

type Pager struct {
    //当前页数,0基
	Page       int         `json:"page"`
	//每页的大小
	PageSize   int         `json:"pageSize"`
	//总的条目数
	TotalItems int         `json:"totalItems"`
	//总的页数
	TotalPages int         `json:"totalPages"`
	//实体的数组
	Data       interface{} `json:"data"`
}

WebResult

WebResult并不是会持久化到数据库中实体,WebResult是在controller返回数据给前端时包装的一层,有了WebResult后每个接口返回的数据会更加统一,方便了前端的统一处理。

type WebResult struct {
    //状态码,具体每个码的意义参考下文
	Code int       `json:"code"`
	//一句话描述请求结果,通常会是出错时指明出错原因,或者修改权限等小操作时提示的`操作成功`
	Msg  string      `json:"msg"`
	//内容可能是一个实体,也可能是一个 Pager.
	Data interface{} `json:"data"`
}

状态码对应关系如下:

const (
	//正常
	RESULT_CODE_OK = 200
	//未登录
	RESULT_CODE_LOGIN = -400
	//没有权限
	RESULT_CODE_UNAUTHORIZED = -401
	//请求错误
	RESULT_CODE_BAD_REQUEST = -402
	//没有找到
	RESULT_CODE_NOT_FOUND = -404
	//登录过期
	RESULT_CODE_LOGIN_EXPIRED = -405
	//该登录用户不是有效用户
	RESULT_CODE_LOGIN_INVALID = -406
	//提交的表单验证不通过
	RESULT_CODE_FORM_INVALID = -410
	//请求太频繁
	RESULT_CODE_FREQUENCY = -420
	//服务器出错。
	RESULT_CODE_SERVER_ERROR = -500
	//远程服务不可用
	RESULT_CODE_NOT_AVAILABLE = -501
	//并发异常
	RESULT_CODE_CONCURRENCY = -511
	//远程微服务没有找到
	RESULT_CODE_SERVICE_NOT_FOUND = -600
	//远程微服务连接超时
	RESULT_CODE_SERVICE_TIME_OUT = -610
	//通用的异常
	RESULT_CODE_UTIL_EXCEPTION = -700
)

二、返回规范

蓝眼云盘采用前后端分离的模式,前端调用后端接口时,url均以/api开头,返回均是json字符串。

  • 返回的json字符串的key均为小写开头的驼峰法,具体参考实体类中json标签

  • 返回的时间格式均为 YYYY-MM-dd HH:mm:ss(例如:2018-01-06 17:57:00)

返回内容均是由WebResult进行包装,因此具有高度的统一性,在这里我们约定一些说法,后面介绍Controller时便不再赘述。

  1. 返回一个XX实体

    指的是WebResultCode=200, Data=一个XX实体对象

    例:返回一个User,则前端会收到以下json字符串:

    {
      "code": 200,
      "msg": "",
      "data": {
        "uuid": "eed2c66d-1de6-47ff-645e-b67beaa10365",
        "sort": 1514803034507,
        "modifyTime": "2018-01-06 18:00:58",
        "createTime": "2018-01-01 18:37:15",
        "role": "USER",
        "username": "demo",
        "email": "demo@tank.eyeblue.cn",
        "phone": "",
        "gender": "UNKNOWN",
        "city": "",
        "avatarUrl": "/api/alien/download/ea490cb6-368e-436d-71c0-fcfb08854c80/1180472.png",
        "lastIp": "124.78.220.82",
        "lastTime": "2018-01-06 18:00:58",
        "sizeLimit": 1048576,
        "status": "OK"
      }
    }
    
  2. 返回XXPager

    指的是WebResultCode=200, Data=XX的Pager

    例:返回UserPager,则前端会收到以下json字符串:

    {
      "code": 200,
      "msg": "",
      "data": {
        "page": 0,
        "pageSize": 10,
        "totalItems": 2,
        "totalPages": 1,
        "data": [
          {
            "uuid": "6a661938-8289-4957-4096-5a1b584bf371",
            "sort": 1515057859613,
            "modifyTime": "2018-01-04 17:26:01",
            "createTime": "2018-01-04 17:24:20",
            "role": "ADMINISTRATOR",
            "username": "simba",
            "email": "y******5@163.com",
            "phone": "",
            "gender": "MALE",
            "city": "",
            "avatarUrl": "/api/alien/download/d1e453cb-3170-4bdb-73f2-fa0372ee017b/1180480.png",
            "lastIp": "180.173.103.207",
            "lastTime": "2018-01-04 17:26:01",
            "sizeLimit": -1,
            "status": "OK"
          },
          {
            "uuid": "e59be6a3-f806-463e-553a-4c5892eedf78",
            "sort": 1514881002975,
            "modifyTime": "2018-01-02 16:16:43",
            "createTime": "2018-01-02 16:16:43",
            "role": "USER",
            "username": "blog_dev",
            "email": "b*****@tank.eyeblue.cn",
            "phone": "",
            "gender": "MALE",
            "city": "",
            "avatarUrl": "/api/alien/download/fdca6eee-d009-4eb3-5ad4-15ba3701cb2e/jump.jpg",
            "lastIp": "",
            "lastTime": "2018-01-02 16:16:43",
            "sizeLimit": 1048576,
            "status": "OK"
          }
        ]
      }
    }
    
  3. 返回错误信息:yyy

    指的是WebResultCode=-400, Msg=yyy。(这里的Code具体值参考上文的code表)

    例:返回错误信息:"【新建文件夹】已经存在了,请使用其他名称。",则前端会收到以下json字符串:

    {
      "code": -700,
      "msg": "【新建文件夹】已经存在了,请使用其他名称。",
      "data": null
    }
    
  4. 返回成功信息:zzz

    指的是WebResultCode=200, Msg=zzz。(这里的Code具体值参考上文的code表)

    例:返回成功信息:"删除成功。",则前端会收到以下json字符串:

    {
      "code": 200,
      "msg": "删除成功。",
      "data": null
    }
    

三、接口

蓝眼云盘所有的接口均定义在controller中,总共定义了以下controller

名称 所在文件 描述
PreferenceController preference_controller.go 网站标题,logo,版权说明等信息的增删改查
MatterController matter_controller.go 站内创建文件夹,上传文件,删除文件,修改权限等
UserController user_controller.go 登录,管理操作站内用户
AlienController alien_controller.go 第三方授权上传,下载,预处理

每个接口都有不同的访问级别,系统中定义了三种访问级别,分别是:

游客 < 注册用户 < 管理员

PreferenceController

该Controller负责网站中的偏好设置,主要操作Preference实体


/api/preference/fetch

功能:读取网站偏好设置,网站名称,logo,版权,备案信息均从此接口读取。

访问级别游客,注册用户,管理员

请求参数:无

返回: 一个Preference实体


/api/preference/edit

功能:编辑网站偏好设置,修改网站名称,logo,版权,备案信息。

访问级别管理员

请求参数

名称 类型 必填性 描述
name string 必填 网站名称
logoUrl string 选填 网站logoUrl,如果不填默认使用蓝眼云盘logo
faviconUrl string 选填 网站faviconUrl,如果不填默认使用蓝眼云盘favicon.ico
footerLine1 string 选填 网站版权所有信息
footerLine2 string 选填 网站备案信息

返回: 一个Preference实体


MatterController

该Controller负责站内创建文件夹,上传文件,删除文件,修改权限等,主要操作Matter实体


/api/matter/create/directory

功能:创建文件夹

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
puuid string 必填 准备创建的目录所在的目录,如果在根目录下创建传root
name string 必填 文件夹名称, 不能包含以下特殊符号:< > | * ? / \

返回: 新建的这个文件夹的Matter实体


/api/matter/upload

功能:上传文件

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
userUuid string 选填 该文件的归属人,如果不填则使用当前登录的用户uuid;如果是管理员要给用户A上传文件,那么这里应该填A的uuid.
alien bool 选填 是否是应用数据,true表示应用数据,这时会自动放置在应用数据这个文件夹下,比如上传头像。false表示非应用数据,这时puuid字段为必填
puuid bool 选填 文件上传到哪个目录下。 如果alien=false,这个字段必填。
privacy bool 选填 文件的私有性,默认false
file file 必填 文件,在浏览器中是通过<input type="file" name="file"/>来选择的

返回: 刚上传的这个文件的Matter实体


/api/matter/delete

功能:删除文件或者文件夹

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 待删除的文件或文件夹的uuid

返回: 成功信息“删除成功”


/api/matter/delete/batch

功能:批量删除文件或文件夹

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuids string 必填 待删除的文件或文件夹的uuids,用逗号(,)分隔。

返回: 成功信息“删除成功”


/api/matter/rename

功能:重命名文件或文件夹

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 文件的uuid
name string 必填 新名字,不能包含以下特殊符号:< > | * ? / \

返回: 刚重命名的这个文件的Matter实体


/api/matter/change/privacy

功能:改变文件的公私有属性

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 文件的uuid
privacy bool 选填 文件的私有性,默认false

返回: 成功信息“设置成功”


/api/matter/move

功能:将一个文件夹或者文件移入到另一个文件夹下。

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
srcUuids string 必填 待移动的文件或文件夹的uuids,用逗号(,)分隔。
destUuid string 必填 目标文件夹,根目录用root

返回: 成功信息“设置成功”


/api/matter/detail

功能:产看文件详情

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 该文件的uuid。
destUuid string 必填 目标文件夹,根目录用root

返回: 这个文件的Matter实体


/api/matter/page

功能:按照分页的方式获取某个文件夹下文件和子文件夹的列表

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
puuid string 选填 文件夹uuid,如果根目录填root
page int 选填 当前页数,0基,默认0
pageSize int 选填 每页条目数,默认200
userUuid string 选填 筛选文件拥有者,对于普通用户使用当前登录的用户uuid.
name string 选填 模糊筛选文件名
dir bool 选填 筛选是否为文件夹
orderDir DESCASC 选填 按文件夹排序,DESC降序排,ASC升序排
orderCreateTime DESCASC 选填 按创建时间排序,DESC降序排,ASC升序排
orderSize DESCASC 选填 按文件大小排序,DESC降序排,ASC升序排
orderName DESCASC 选填 按名称排序,DESC降序排,ASC升序排
extensions string 选填 按文件后缀名筛选,逗号(,)分隔。例:jpg,png,pdf

返回: MatterPager


/api/alien/download/{uuid}/{filename}

这个接口的定义在在AlienController中的,具体使用请参考蓝眼云盘编程接口 这里只做简单的下载使用。

功能:下载文件。

访问级别游客,注册用户,管理员

请求参数: 均是放置在url中

名称 类型 必填性 描述
uuid string 必填 要下载的文件uuid
filename string 必填 要下载的文件名

返回: 二进制的文件


UserController

该Controller负责站内创建文件夹,上传文件,删除文件,修改权限等,主要操作Matter实体


/api/user/create

功能:创建用户

访问级别管理员

请求参数

名称 类型 必填性 描述
username string 必填 用户名,且只能包含字母,数字和'_'
password string 必填 密码,密码长度至少为6位
email string 必填 邮箱,作为用户登录的凭证
avatarUrl string 选填 头像
phone string 选填 电话
gender string 选填 性别
role string 选填 角色
city string 选填 城市
sizeLimit string 选填 用户上传单文件限制,单位byte. 如果负数表示无限制。

返回: 新建的User实体


/api/user/edit

功能:编辑用户

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 待编辑的用户uuid
avatarUrl string 选填 头像
phone string 选填 电话
gender string 选填 性别
role string 选填 角色
city string 选填 城市
sizeLimit string 选填 用户上传单文件限制,单位byte. 如果负数表示无限制。

返回: 编辑的User实体


/api/user/change/password

功能:用户修改密码

访问级别注册用户,管理员

请求参数

名称 类型 必填性 描述
oldPassword string 必填 旧密码
newPassword string 必填 新密码

返回: 修改密码的User实体


/api/user/change/password

功能:管理员重置用户密码

访问级别管理员

请求参数

名称 类型 必填性 描述
userUuid string 必填 待重置密码的用户uuid
password string 必填 密码

返回: 修改密码的User实体


/api/user/login

功能:登录

访问级别游客,注册用户,管理员

请求参数

名称 类型 必填性 描述
email string 必填 邮箱
password string 必填 密码

返回: 当前登录的User实体


/api/user/logout

功能:登录

访问级别注册用户,管理员

请求参数:无

返回: 成功信息"退出成功!"


/api/user/detail

功能:查看用户详情

访问级别游客,注册用户,管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 待查看的用户uuid

返回: User实体


/api/user/page

功能:查看用户列表

访问级别管理员

请求参数

名称 类型 必填性 描述
page int 选填 当前页数,0基,默认0
pageSize int 选填 每页条目数,默认200
username string 选填 模糊筛选用户名
email string 选填 模糊筛选邮箱
phone string 选填 模糊筛选电话
orderLastTime DESCASC 选填 按上次登录时间排序,DESC降序排,ASC升序排
orderCreateTime DESCASC 选填 按创建时间排序,DESC降序排,ASC升序排

返回: User实体的Pager


/api/user/disable

功能:禁用用户

访问级别管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 待操作的用户

返回: 被操作的用户User实体


/api/user/enable

功能:启用用户

访问级别管理员

请求参数

名称 类型 必填性 描述
uuid string 必填 待操作的用户

返回: 被操作的用户User实体


AlienController

这个Controller主要暴露给第三方使用,详情请参考:蓝眼云盘编程接口