Skip to main content
Version: 3.0.0

接口开发

路由

在 Midway Hooks 中,你可以通过 @midwayjs/hooks 提供的 Api() 函数来快速创建接口。

Hello World 示例:

/src/hello.ts
import {
Api,
Get,
} from '@midwayjs/hooks';

export default Api(
Get(), // Http Path: /api/hello,
async () => {
return 'Hello World!';
}
);

一个 API 接口由以下部分组成:

  • Api():定义接口函数
  • Get(path?: string):指定 Http 触发器,指定请求方法为 GET,可选参数 path 为接口路径,不指定路径的情况下会根据函数名 + 文件名生成路径,默认带有 /api 前缀
  • Handler: async (...args: any[]) => { ... }:用户逻辑,处理请求并返回结果

你也可以指定路径,例子如下。

/src/hello.ts
import {
Api,
Get,
} from '@midwayjs/hooks';

export default Api(
Get('/hello'), // Http Path: /hello,
async () => {
return 'Hello World!';
}
);

请求上下文(Context / Request / Response)

你可以通过 @midwayjs/hooks 提供的 useContext 来获取请求上下文对象。

以使用 Koa 框架为例,那么 useContext 将返回 Koa 的 Context 对象。

基础示例:

  1. 获取请求 Method 和 Path
import {
Api,
Get,
useContext,
} from '@midwayjs/hooks';
import { Context } from '@midwayjs/koa';

export default Api(Get(), async () => {
const ctx = useContext<Context>();
return {
method: ctx.method,
path: ctx.path,
};
});
  1. 设置返回的 Header
import {
Api,
Get,
useContext,
} from '@midwayjs/hooks';

export default Api(Get(), async () => {
const ctx = useContext<Context>();
ctx.set('X-Powered-By', 'Midway');
return 'Hello World!';
});

同时我们也可以通过 SetHeader() 来设置 Header。

Http 触发器

触发器注释
All(path?: string)接受所有 Http Method 的请求
Get(path?: string)接受 GET 请求
Post(path?: string)接受 POST 请求
Put(path?: string)接受 PUT 请求
Delete(path?: string)接受 DELETE 请求
Patch(path?: string)接受 PATCH 请求
Head(path?: string)接受 HEAD 请求
Options(path?: string)接受 OPTIONS 请求

当生成前端 SDK 时,如果 Method 为 All,则 Method 生成规则为:有参数 -> Post,没参数 -> Get

请求 Request

传递参数 Data

在 Midway Hooks 中,接口的入参就是声明函数的参数。

基础示例如下:

import {
Api,
Post,
} from '@midwayjs/hooks';

export default Api(
Post(), // Http Path: /api/say,
async (name: string) => {
return `Hello ${name}!`;
}
);

你可以用两种方式来调用接口。

  1. 全栈项目:基于零 Api,导入接口并调用
  2. 手动调用:使用 fetch 在 Http 下,Handler(...args: any[]) 的入参,可以在手动请求时通过设置 Http Body 的 args 参数来传递参数。
import say from './api';

const response = await say('Midway');
console.log(response); // Hello Midway!

查询参数 Query

查询参数可以实现在 URL 上传递参数的方式,使用该功能时,必须通过 Query<T> 声明类型。

如果希望接口路径是 /articles?page=0&limit=10,可以这样写。

import {
Api,
Get,
Query,
useContext,
} from '@midwayjs/hooks';

export default Api(
Get(),
Query<{
page: string;
limit: string;
}>(),
async () => {
const ctx = useContext();
return {
page: ctx.query.page,
limit: ctx.query.limit,
};
}
);

前端调用

import getArticles from './api';
const response = await getArticles({
query: { page: '0', limit: '10' },
});
console.log(response); // { page: '0', limit: '10' }

路径参数 Params

路径参数可以实现动态路径和从路径中获取参数的功能。使用该功能时,必须手动设置路径,并通过 Params<T> 声明类型。

如果希望接口路径是 /article/100,并获取 id 为 100 的值,可以这样写:

import {
Api,
Get,
Params,
useContext,
} from '@midwayjs/hooks';

export default Api(
Get('/article/:id'),
Params<{ id: string }>(),
async () => {
const ctx = useContext();
return {
article: ctx.params.id,
};
}
);

前端调用

import getArticle from './api/article';
const response = await getArticle({
params: { id: '100' },
});
console.log(response); // { article: '100' }

请求头 Headers

请求头可以实现通过 Http Headers 传递参数的功能,使用该功能时,必须通过 Headers<T> 声明类型。

如果希望请求 /auth,并在 Request Headers 中 传递 token,可以这样写:

import {
Api,
Get,
Headers,
useContext,
} from '@midwayjs/hooks';

export default Api(
Get('/auth'),
Headers<{ token: string }>(),
async () => {
const ctx = useContext();
return {
token: ctx.headers.token,
};
}
);

前端调用

import getAuth from './api/auth';
const response = await getAuth({
headers: { token: '123456' },
});
console.log(response); // { token: '123456' }

响应 Response

状态码 HttpCode

支持 HttpCode(status: number)

import {
Api,
Get,
HttpCode,
} from '@midwayjs/hooks';

export default Api(
Get(),
HttpCode(201),
async () => {
return 'Hello World!';
}
);

响应头 SetHeader

支持 SetHeader(key: string, value: string)

import {
Api,
Get,
SetHeader,
} from '@midwayjs/hooks';

export default Api(
Get(),
SetHeader('X-Powered-By', 'Midway'),
async () => {
return 'Hello World!';
}
);

重定向 Redirect

支持: Redirect(url: string, code?: number = 302)

import {
Api,
Get,
Redirect,
} from '@midwayjs/hooks';

export default Api(
Get('/demo'),
Redirect('/hello'),
async () => {}
);

返回值类型 ContentType

支持: ContentType(type: string)

import {
Api,
Get,
ContentType,
} from '@midwayjs/hooks';

export default Api(
Get(),
ContentType('text/html'),
async () => {
return '<h1>Hello World!</h1>';
}
);