前端开发公共事项

[Starrah]

@mayeths @BluesCrossing
考虑到前端代码开发经常会有一些公共的声明、规则乃至轮子，此issue专用于记录此事。
在为前端开发制定公共规范方面大家的权利是平等的：

1. 如果一件事在此前没有规范，任何人都可以制定一个新的规范，直接回复在此。其他人如有建议，请尽快提出；
2. 如果一件事在此前有规范，但是因为过去的制定不合理而导致需要修改，则希望修改者可以视严重程度选择微信聊天/issue讨论/线下会议等方式讨论，达成新的规范共识后修改。

[Starrah]

关于类型声明：
一些重要的类型，如用户信息、活动信息等，统一声明在app/typesDeclare文件夹里。
例如：

[Starrah]

关于网络请求：

1. 根据与后端约定的规范，所有错误的请求应当返回一个JSON数据包
   {errid: number, errmsg: string}
   其中当errid是1-499时为特定返回码，其含义和前后端的处理方式由具体API文档约定（在yapi上）；
   errid为500-599时为非特定返回码，此时后端保证返回的errmsg是用户可以理解的汉字，前端所做的是只要把errmsg展现给用户即可。
2. 请求尽量使用promisify.request函数，用法：

//app/promisify.ts
promisify.request({
    url: string;
    data?: string | object | ArrayBuffer;
    header?: any;
    method: 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'CONNECT';
    dataType?: string; //如果设为json，会尝试对返回的数据做一次 JSON.parse
})

返回：一个Promise：
当网络请求成功，且返回状态码为2XX时，其resolve为一个网络请求对象：

{
    data?: string | any | ArrayBuffer;
    statusCode: number;
    header?: any;
}

当网络请求得到返回值但返回值为4XX或5XX时，其reject为一个异常对象：

{
    data?: {errid: number, errmsg: string};
    statusCode: number;
    header?: any;
}

其中如果返回的errid为500-599时，会自动调用uni.showToast方法把异常信息提示给用户，调用者无需再次处理

当网络请求失败（没有得到返回值时），其reject为系统自带的异常对象。

用法示例：

        async updateAllActivity(){
            let res = await promisify.request({
                url: getApp().globalData.baseUrl + `/getAllActivity?openId=${getApp().globalData.openId}`,
                method: "GET",
                dataType: "json",
            });
            this.activities_toShow = res.data.activityList
        }

请注意，promisify.request方法返回的是Promise对象；只有在async函数才能使用await，对一个Promise使用await，当成功时会返回它所resolve的对象，当失败时会抛出异常。

[Starrah]

关于UserInfo类的定义：

//app/typesDeclare/UserInfo.ts
interface UserInfo {
    openId: string;
    name: string;
    education: Array<{
        type: string,
        start: number,
        department: string,
    }>
    flag: string
}

[Starrah]

关于活动信息类的定义：

//app/types/ActivitySchema.d.ts
interface ActivitySchema{
    id: string,
    name: string,
    place: string,
    start: string, //yyyy-mm-dd hh:MM:ss
    end: string, //yyyy-mm-dd hh:MM:ss
    minUser?: number
    maxUser?: number,
    curUser: number,
    creator: string,
    signupBeginAt: string,
    signupStopAt: string, //yyyy-mm-dd hh:MM:ss
    participants: [string]
    type: string,
    status: ActivityStatus
}

declare enum ActivityStatus {
    Except = 0, //异常情况（如活动被管理员禁止等）
    BeforeSignup = 1, //报名尚未开始
    Signup = 2, //报名中
    SignupPaused = 3, //报名被暂停（发起人主动）
    SignupStopped = 4, //报名已截止（到达设定的时间）
    Signin = 5, //签到中
    SigninPaused = 6, //签到被暂停
    Finish = 7, //活动已结束（到达设定的活动结束时间）
}

[mayeths]

关于网络请求：

1. 根据与后端约定的规范，所有错误的请求应当返回一个JSON数据包
   {errid: number, errmsg: string}
   其中当errid是1-499时为特定返回码，其含义和前后端的处理方式由具体API文档约定（在yapi上）；
   errid为500-599时为非特定返回码，此时后端保证返回的errmsg是用户可以理解的汉字，前端所做的是只要把errmsg展现给用户即可。

这种返回码是不规范的。在 RESTful API规范 或者一般的 HTTP规范 中，返回码均有特定的含义，这是普遍认可的标准。

常见的返回码：

返回码	含义
1xx	中间状态
2xx	成功
3xx	重定向
4xx	Client Failed, e.g., 请求无效
5xx	Server Failed, e.g., 服务器正忙或无法预知的错误
200	OK - [GET]：服务器成功返回用户请求的数据。
201	CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202	Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204	NO CONTENT - [DELETE]：用户删除数据成功。
400	INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误
401	Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403	Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404	NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作.
406	Not Acceptable - [GET]：用户请求的格式不可得（如请求JSON格式，但只有XML格式）
410	Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422	Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500	INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

[Starrah]

这种返回码是不规范的。在 RESTful API规范 或者一般的 HTTP规范 中，返回码均有特定的含义，这是普遍认可的标准。

补充：
上述errid和errmsg不同于HTTP返回码；HTTP返回码是对HTTP请求的执行情况的一般化的描述（如成功200/失败4xx，其中如果是请求被服务器正常接受但是存在业务逻辑层面的问题则为400、没有权限401/403、url对应资源不存在404等），主要是针对请求的处理层的执行结果描述，而不讨论业务逻辑层的执行结果。
我们的项目中，如果是服务器理解了请求但是存在业务逻辑上的错误（举例而言，活动结束日期早于开始日期），这种情况下一律返回HTTP 400状态码是合理的。（当然在特殊情况下，比如url不存在时，HTTP 404仍然适用，只是如果代码没有bug的话一般是不会出现404请求的。）
但是只有HTTP 400，是不足以描述发生错误的详细信息的。因此规定了用于补充说明错误具体内容的errid。上述规定与标准HTTP状态码规范并不冲突，或者说errid是对HTTP 400包含的各种错误情况的子集。
以上errid和errmsg的模式已有成熟实践，如微信公众平台接口

[Starrah]

SureModal使用方法：
1.在每个页面引入组件：

<SureModal ref="SureModal"></SureModal>

2.在需要使用的地方：

await ((this.$refs.SureModal as any).show("您确定要发起这个活动吗？"));

（注：this.$refs.SureModal拿到的引用是Vue类型，必须转为any后才能调用show方法，传入的字符串参数是提示信息文字）
3.上述show方法返回promise，在用户点击确定后resolve，点击取消后reject。
4.使用实例：

    async attendCurActivity(){
            await ((this.$refs.SureModal as any).show("您报名后无需审核，可以直接加入本活动。\r\n确认要报名参加本活动吗？"));
            let res = apiService.post(`/joinActivity?activityId=${this.activityId}`, {})
            if(res && res.result === 'success'){
                uni.showToast({
                    title: "报名成功"
                });
            }else{
                uni.showToast({
                    title: (res && res.errmsg) || '参加失败',
                    icon: "none"
                })
            }
            this.updateActivityData()
        }