Skip to content

Commit

Permalink
Correct api jsdocs
Browse files Browse the repository at this point in the history
  • Loading branch information
otomad committed Oct 29, 2023
1 parent d27e5b2 commit 4ca38c2
Show file tree
Hide file tree
Showing 11 changed files with 92 additions and 89 deletions.
1 change: 1 addition & 0 deletions .eslintrc.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,7 @@ module.exports = {
"no-labels": "off",
"default-case-last": "off",
"no-useless-constructor": "off", // private constructor() { } 你跟我说无用?
"no-multiple-empty-lines": ["error", { max: 1, maxEOF: 0, maxBOF: 0 }],
"import/order": "off", // 与 VSCode 内置导入排序特性打架。
"import/first": "off", // 与 Vue 特性冲突。
"import/named": "off", // 与 TypeScript 特性冲突。
Expand Down
2 changes: 1 addition & 1 deletion components/Thumb/ThumbVideo.vue
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
<LocaleLink class="thumb-video lite" :to="link" :blank="blank">
<div class="card">
<div class="cover-wrapper">
<img :src="image" alt="cover" class="cover" />
<img :src="image" alt="cover" class="cover" :draggable="false" />
</div>
<div class="text-wrapper">
<div class="title"><slot>视频标题</slot></div>
Expand Down
Empty file added composables/api.ts
Empty file.
3 changes: 0 additions & 3 deletions composables/api/Common/GetCorrectUri.ts

This file was deleted.

7 changes: 7 additions & 0 deletions composables/api/Common/getCorrectUri.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
/**
* 根据当前环境(开发或生产)确定正确的后端地址。
* @returns 正确的后端地址。
*/
export default function getCorrectUri() {
return environment.production ? "https://rosales.kirakira.moe" : "https://localhost:9999";
}
5 changes: 2 additions & 3 deletions composables/api/User/UserController.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import { get, post } from "../Common";
import { getCorrectUri } from "../Common/GetCorrectUri";
import { get, post } from "api/Common";
import getCorrectUri from "api/Common/getCorrectUri";
import type { UserExistsCheckDataDto, UserExistsCheckResultDto, UserLoginDataDto, UserLoginResultDto, UserRegistrationDataDto, UserRegistrationResultDto } from "./UserControllerDto";


const BACK_END_URL = getCorrectUri();
const USER_API_URI = `${BACK_END_URL}/user`;

Expand Down
40 changes: 20 additions & 20 deletions composables/api/User/UserControllerDto.d.ts
Original file line number Diff line number Diff line change
@@ -1,73 +1,73 @@
/**
* 用户注册提交的参数
* @param username 用户名
* @param passwordHash 在前端已经 Hash 过一次的的密码
* @param passwordHint 密码提示
*/
export type UserRegistrationDataDto = {
/** 用户名 */
username: string;
/** 在前端已经 Hash 过一次的的密码 */
passwordHash: string;
/** 密码提示 */
passwordHint?: string;
};

/**
* 用户注册的返回参数
* @param success 执行结果,程序执行成功,返回 true,程序执行失败,返回 false
* @param uid 用户 ID
* @param token 如果注册成功,则返回一个 token,如果注册失败,则 token 是一个假值(undefined、null 或 '')
* @param message 附加的文本消息
*/
export type UserRegistrationResultDto = {
/** 执行结果,程序执行成功,返回 true,程序执行失败,返回 false */
success: boolean;
/** 用户 ID */
uid?: number;
/** 如果注册成功,则返回一个 token,如果注册失败,则 token 是一个假值(undefined、null 或 "") */
token?: string;
/** 附加的文本消息 */
message?: string;
};

/**
* 用户登录提交的参数
* @param username 用户名
* @param passwordHash 在前端已经 Hash 过一次的的密码
*/
export type UserLoginDataDto = {
/** 用户名 */
username: string;
/** 在前端已经 Hash 过一次的的密码 */
passwordHash: string;
};

/**
* 用户登录的返回参数
* @param success 执行结果,程序执行成功,返回 true,程序执行失败,返回 false
* @param username 用户名
* @param uid 用户 ID
* @param token 如果登录成功,则返回一个 token,如果登录失败,则 token 是一个假值(undefined、null 或 '')
* @param passwordHint 密码提示
* @param message 附加的文本消息
*/
export type UserLoginResultDto = {
/** 执行结果,程序执行成功,返回 true,程序执行失败,返回 false */
success: boolean;
/** 用户名 */
username?: string;
/** 用户 ID */
uid?: number;
/** 如果登录成功,则返回一个 token,如果登录失败,则 token 是一个假值(undefined、null 或 '') */
token?: string;
/** 密码提示 */
passwordHint?: string;
/** 附加的文本消息 */
message?: string;
};

/**
* 验证用户是否存在提交的参数
* @param username 用户名
*/
export type UserExistsCheckDataDto = {
/** 用户名 */
username: string;
};

/**
* 验证用户是否已经存在的返回参数
* @param success 执行结果,程序执行成功,返回 true,程序执行失败,返回 false
* @param exists 用户存在或者查询失败(悲观)都会返回 true,不存在返回 false // WARN 注意:用户存在或查询失败时都会返回 true
* @param message 附加的文本消息
*/
export type UserExistsCheckResultDto = {
/** 执行结果,程序执行成功,返回 true,程序执行失败,返回 false */
success: boolean;
exists: boolean;
/** 用户存在或者查询失败(悲观)都会返回 true,不存在返回 false */
exists: boolean; // WARN 注意:用户存在或查询失败时都会返回 true
/** 附加的文本消息 */
message?: string;
};
6 changes: 3 additions & 3 deletions composables/api/Video/VideoController.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { getCorrectUri } from "../Common/GetCorrectUri";
import { GetVideoByKvidResponseDto, ThumbVideoResponseDto, getVideoByKvidRequestDto } from "./VideoControllerDto";
import getCorrectUri from "api/Common/getCorrectUri";
import type { GetVideoByKvidResponseDto, ThumbVideoResponseDto, GetVideoByKvidRequestDto } from "./VideoControllerDto";

const BACK_END_URL = getCorrectUri();
const VIDEO_API_URI = `${BACK_END_URL}/video`;
Expand All @@ -12,7 +12,7 @@ export const getHomePageThumbVideo = async (): Promise<ThumbVideoResponseDto> =>
return { success: false, videosCount: 0, videos: [], message: "获取首页视频失败" };
};

export const getVideoByKvid = async (getVideoByKvidRequest: getVideoByKvidRequestDto): Promise<GetVideoByKvidResponseDto> => {
export const getVideoByKvid = async (getVideoByKvidRequest: GetVideoByKvidRequestDto): Promise<GetVideoByKvidResponseDto> => {
if (getVideoByKvidRequest && getVideoByKvidRequest.videoId) {
const { data: result } = await useFetch<GetVideoByKvidResponseDto>(`${VIDEO_API_URI}?videoId=${getVideoByKvidRequest.videoId}`);
if (result.value)
Expand Down
95 changes: 48 additions & 47 deletions composables/api/Video/VideoControllerDto.d.ts
Original file line number Diff line number Diff line change
@@ -1,43 +1,43 @@
/**
* @param id 分P ID
* @param 视频 分P 标题
* @param 视频直链
* 单个视频分 P 数据参数
*/
type videoPartDto = {
type VideoPartDto = {
/** 分 P ID */
id: number;
/** 视频分 P 标题 */
videoPartTitle: string;
/** 视频直链 */
link: string;
};
/**
* 展示视频卡片返回的参数
* @param videoPart 每 P 视频的数据
* @param videoPartDto[] 每 P 视频的数据
* @param title 视频标题
* @param image 封面图链接
* @param uploader 视频作者 ID
* @param uploaderId 创作者 UID
* @param duration 视频时长,单位 ms
* @param description 视频描述
*/
export type UploadVideoRequestDto = {
videoPart: videoPartDto[];
/** 每 P 视频的数据 */
videoPart: VideoPartDto[];
/** 视频标题 */
title: string;
/** 封面图链接 */
image: string;
/** 视频作者 ID */
uploader: string;
/** 创作者 UID */
uploaderId: number;
/** 视频时长,单位 ms */
duration: number;
/** 视频描述 */
description?: string;
};

/**
* 视频上传的返回的参数
* @param success 是否请求成功
* @param message 附加的文本消息
* @parma videoId 视频 ID
*/
export type UploadVideoResponseDto = {
/** 是否请求成功 */
success: boolean;
/** 附加的文本消息 */
message?: string;
/** 视频 ID */
videoId?: number;
};

Expand All @@ -47,75 +47,76 @@ export type UploadVideoResponseDto = {

/**
* 展示视频卡片需要的返回参数
* @param success 是否请求成功
* @param message 附加的文本消息
* @param videosCount 获取到的视频数量,如果没获取到则为 0
* @param videos 请求到的视频的数据
* @param videoId KVID 视频 ID
* @param title 视频标题
* @param image 封面图链接
* @param updateDate 频上传的日期,时间戳格式
* @param watchedCount 视频播放量
* @param uploader 视频作者 ID
* @param uploaderId 创作者 UID
* @param duration 视频时长,单位 ms
* @param description 视频描述
*/
export type ThumbVideoResponseDto = {
/** 是否请求成功 */
success: boolean;
/** 附加的文本消息 */
message?: string;
/** 获取到的视频数量,如果没获取到则为 0 */
videosCount: number;
/** 请求到的视频的数据 */
videos: {
/** 视频 ID (KVID) */
videoId: number;
/** 视频标题 */
title: string;
/** 封面图链接 */
image?: string;
/** 视频上传的日期,时间戳格式 */
updateDate?: number;
/** 视频播放量 */
watchedCount?: number;
/** 视频作者 ID */
uploader?: string;
/** 创作者 UID */
uploaderId?: number;
/** 视频时长,单位 ms */
duration?: number;
/** 视频描述 */
description?: string;
}[];
};

/**
* @param videoId kvid 视频的自增 ID
* 从视频 ID 获取视频的请求
*/
export type getVideoByKvidRequestDto = {
export type GetVideoByKvidRequestDto = {
/** kvid 视频的自增 ID */
videoId: number;
};

/**
* 视频页面需要的响应
* @param success 是否请求成功
* @param message 附加的文本消息
* @param videosCount 获取到的视频数量,如果没获取到则为 0
* @param video 请求到的视频的数据
* @param videoId KVID 视频 ID
* @param videoPart 视频 分P 数据
* @param videoPartDto[] 视频 分P 数据
* @param title 视频标题
* @param image 封面图链接
* @param updateDate 频上传的日期,时间戳格式
* @param watchedCount 视频播放量
* @param uploader 视频作者 ID
* @param uploaderId 创作者 UID
* @param duration 视频时长,单位 ms
* @param description 视频描述
*/
export type GetVideoByKvidResponseDto = {
/** 是否请求成功 */
success: boolean;
/** 附加的文本消息 */
message?: string;
/** 获取到的视频数量,如果没获取到则为 0 */
// videosCount: number;
/** 请求到的视频的数据 */
video?: {
/** 视频 ID (KVID) */
videoId: number;
videoPart: videoPartDto[];
/** 视频分 P 数据 */
videoPart: VideoPartDto[];
/** 视频标题 */
title: string;
/** 封面图链接 */
image?: string;
/** 视频上传的日期,时间戳格式 */
updateDate?: number;
/** 视频播放量 */
watchedCount?: number;
/** 视频作者 ID */
uploader?: string;
/** 创作者 UID */
uploaderId?: number;
/** 视频时长,单位 ms */
duration?: number;
/** 视频描述 */
description?: string;
};
};
1 change: 1 addition & 0 deletions nuxt.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ export default defineNuxtConfig({
"utils",
"worklets",
"assets/pomsky",
"composables/api",
),
css: [
"styles/global.scss",
Expand Down
21 changes: 9 additions & 12 deletions pages/video/kv[kvid].vue
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<script setup lang="ts">
import exampleVideoPath from "assets/videos/shibamata.mp4";
import { getVideoByKvid } from "~/composables/api/Video/VideoController";
import { getVideoByKvidRequestDto } from "~/composables/api/Video/VideoControllerDto";
import type { GetVideoByKvidRequestDto } from "~/composables/api/Video/VideoControllerDto";
// const exampleVideoPath = "https://video_api.kms233.com/bili/av9912788";
// 暂时不要用在线视频链接,虽然可以用,但是每次查看视频详细信息我都要等好久。
Expand All @@ -21,16 +21,13 @@
* Fetch video data.
*/
async function fetchData() {
// const api = useApi();
const handleError = (e: unknown) => console.error(e);
if (Number.isFinite(kvid)) {
const getVideoByKvidRequest: getVideoByKvidRequestDto = { videoId: kvid };
const getVideoByKvidRequest: GetVideoByKvidRequestDto = { videoId: kvid };
const videoDataResponse = await getVideoByKvid(getVideoByKvidRequest);
if (videoDataResponse.success) {
const videoData = videoDataResponse.video;
const videoPartData = videoData?.videoPart?.[0]; // TODO // WARN 因为要做 分P 视频,所以这里获取到的视频是一个数组,这里暂时取了数组第 0 位。应改进为读取数组中的所有视频,并根据 id 排序渲染成 分P 列表
if (videoData && videoData.title && videoPartData && videoPartData.link) {
const videoPartData = videoData?.videoPart?.[0]; // TODO 因为要做 分P 视频,所以这里获取到的视频是一个数组,这里暂时取了数组第 0 位。应改进为读取数组中的所有视频,并根据 id 排序渲染成 分P 列表
if (videoData?.title && videoPartData?.link) {
videoSource.value = videoPartData.link;
title.value = videoData.title;
videoDetails.value = {
Expand All @@ -40,11 +37,11 @@
uploadDate: videoData.updateDate,
};
} else
useToast("获取视频失败,结果异常", "error"); // TODO 使用多语言
useToast("获取视频失败,结果异常", "error"); // TODO 使用多语言
} else
useToast("获取视频失败,请求失败", "error"); // TODO 使用多语言
useToast("获取视频失败,请求失败", "error"); // TODO 使用多语言
} else {
useToast("未获取到视频 ID,开始使用默认视频", "error"); // TODO 使用多语言
useToast("未获取到视频 ID,开始使用默认视频", "error"); // TODO 使用多语言
videoSource.value = exampleVideoPath;
videoDetails.value = {
title: "柴又",
Expand Down Expand Up @@ -111,14 +108,14 @@
:fans="videoDetails?.userSubscribers ?? 0"
isFollowed
/>
<!-- <Subheader
v-if="(recommendations?.length ?? 0) > 0"
class="recommendations-header"
icon="movie"
:badge="recommendations?.length"
>{{ t.video_recommendations }}</Subheader>
<ThumbVideo
v-for="video in recommendations"
:key="video.videoID"
Expand Down

0 comments on commit 4ca38c2

Please sign in to comment.