diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 06c2ee6..6f4ab49 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,4 +1,5 @@ import { defineConfig } from 'vitepress' +import sidebar from "./sidebar/index" // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -12,26 +13,9 @@ export default defineConfig({ { text: 'Home', link: '/' }, { text: 'Documentation', link: '/introduction' } ], - - sidebar: [ - { text: '简介', link: '/introduction' }, - { - text:"概览", - items:[ - { text: '第一步', link: '/overview/first-step' }, - ] - }, - { - text: 'Examples', - items: [ - { text: 'Markdown Examples', link: '/markdown-examples' }, - { text: 'Runtime API Examples', link: '/api-examples' } - ] - } - ], - + sidebar, socialLinks: [ - { icon: 'github', link: 'https://github.com/vuejs/vitepress' } + { icon: 'github', link: 'https://github.com/fzhange/nestJs-docs' } ] } }) diff --git a/.vitepress/sidebar/index.ts b/.vitepress/sidebar/index.ts new file mode 100644 index 0000000..6203d34 --- /dev/null +++ b/.vitepress/sidebar/index.ts @@ -0,0 +1,5 @@ +import overview from "./overview" +export default [ + { text: '简介', link: '/introduction' }, + overview +] \ No newline at end of file diff --git a/.vitepress/sidebar/overview.ts b/.vitepress/sidebar/overview.ts new file mode 100644 index 0000000..9357262 --- /dev/null +++ b/.vitepress/sidebar/overview.ts @@ -0,0 +1,8 @@ +export default { + text:"概览", + items:[ + { text: '第一步', link: '/overview/first-step' }, + { text: 'controller(控制器)', link: '/overview/controller' }, + // + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 6868613..49a9898 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # 简介 +![Hi](https://nestjs.com/header.1af6756a.png) + NestJS(nestjs.com)致力于构建一个高效、可扩展且结构清晰的Node.js服务器端应用开发框架。其愿景是通过采用渐进式JavaScript和TypeScript语言特性,结合面向对象编程(OOP)、函数式编程(FP)以及函数响应式编程(FRP)的优势,为开发者提供强大的工具链与优雅的开发体验,从而简化企业级应用程序的构建过程,并促进团队协作与项目维护。 本文档致力热衷于将NestJS这一先进的Node.js框架的官方文档及教程等内容翻译成中文,旨在为广大的中文开发者群体提供便利,帮助他们更好地理解和掌握NestJS的核心理念和技术特点。通过精准、流畅的翻译,我希望消除语言障碍,让更多国内开发者能够轻松地利用NestJS构建高效、可维护的企业级应用,并在项目开发过程中受益于其优雅的设计与强大的功能。同时,我也期待通过我的努力,推动国内Node.js生态的发展和繁荣,加强国内外技术社区之间的交流与合作。 diff --git a/api-examples.md b/api-examples.md deleted file mode 100644 index 6bd8bb5..0000000 --- a/api-examples.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -outline: deep ---- - -# Runtime API Examples - -This page demonstrates usage of some of the runtime APIs provided by VitePress. - -The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files: - -```md - - -## Results - -### Theme Data -
{{ theme }}
- -### Page Data -
{{ page }}
- -### Page Frontmatter -
{{ frontmatter }}
-``` - - - -## Results - -### Theme Data -
{{ theme }}
- -### Page Data -
{{ page }}
- -### Page Frontmatter -
{{ frontmatter }}
- -## More - -Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata). diff --git a/deploy.sh b/deploy.sh deleted file mode 100644 index 6183c4c..0000000 --- a/deploy.sh +++ /dev/null @@ -1,38 +0,0 @@ -#!/usr/bin/env sh - -# 确保脚本抛出遇到的错误 - -set -e - -# 生成静态文件 - -# npm install - -npm run docs:build - -# 进入生成的文件夹 - -cd ./.vitepress/dist - -# 如果是发布到自定义域名 -echo 'fzhange.github.io' > CNAME - -git init - -git add . - -git commit -m 'deploy' - -# 如果发布到 https://.github.io - -# git push -f git@github.com:/.github.io.git main - -# 如果发布到 https://.github.io/ - -git remote add origin git@github.com:fzhange/nestJs-docs.git - -git branch -M master - -git push -f git@github.com:fzhange/nestJs-docs.git master:gh-pages - -cd - \ No newline at end of file diff --git a/images/controller.png b/images/controller.png new file mode 100644 index 0000000..ea24645 Binary files /dev/null and b/images/controller.png differ diff --git a/images/decorator-list.png b/images/decorator-list.png new file mode 100644 index 0000000..44b13a1 Binary files /dev/null and b/images/decorator-list.png differ diff --git a/index.md b/index.md index 61bba3b..1c3453b 100644 --- a/index.md +++ b/index.md @@ -1,5 +1,6 @@ --- # https://vitepress.dev/reference/default-theme-home-page +# https://vitepress.dev/guide/markdown layout: home hero: diff --git a/markdown-examples.md b/markdown-examples.md deleted file mode 100644 index f9258a5..0000000 --- a/markdown-examples.md +++ /dev/null @@ -1,85 +0,0 @@ -# Markdown Extension Examples - -This page demonstrates some of the built-in markdown extensions provided by VitePress. - -## Syntax Highlighting - -VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting: - -**Input** - -````md -```js{4} -export default { - data () { - return { - msg: 'Highlighted!' - } - } -} -``` -```` - -**Output** - -```js{4} -export default { - data () { - return { - msg: 'Highlighted!' - } - } -} -``` - -## Custom Containers - -**Input** - -```md -::: info -This is an info box. -::: - -::: tip -This is a tip. -::: - -::: warning -This is a warning. -::: - -::: danger -This is a dangerous warning. -::: - -::: details -This is a details block. -::: -``` - -**Output** - -::: info -This is an info box. -::: - -::: tip -This is a tip. -::: - -::: warning -This is a warning. -::: - -::: danger -This is a dangerous warning. -::: - -::: details -This is a details block. -::: - -## More - -Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown). diff --git a/overview/controller.md b/overview/controller.md new file mode 100644 index 0000000..7fc2110 --- /dev/null +++ b/overview/controller.md @@ -0,0 +1,72 @@ +# Controllers(控制器) + +控制器负责处理传入的请求并返回对客户的响应。 +![alt text](../images/controller.png) + +控制器的目的是接收该应用程序的特定请求.路由机制控制哪个控制器接受哪个请求,每个控制器都有多个路由,不同的路由可以执行不同的操作。 +为了创建基本控制器,我们使用类和装饰器(decorators)。基于元数据的装饰器与类做关联,创建一个Nest的路由映射图。(绑定请求到对应的控制器上)。 + +:::tip +如果你想快速的创建一个使用内置[验证器(validation)](https://docs.nestjs.com/techniques/validation)的CRUD应用,你可以使用[NEST CLI生成器](https://docs.nestjs.com/recipes/crud-generator#crud-generator)的能力。 nest g resource [name]. +::: + +## Routing(路由) + +下面的例子中,我们会使用@Controller()装饰符,它被用来定义一个Controller(控制器)。我们将指定一个前缀是cats的路由。这种形式可以让我们快速的对路由进行分组,同时降低代码重复。 + +```Js +import { Controller, Get } from '@nestjs/common'; + +@Controller('cats') +export class CatsController { + @Get() + findAll(): string { + return 'This action returns all cats'; + } +} +``` + +:::tip 使用CLI快速创建一个Controller +`nest g controller [name]` +::: + +在上面的示例中,当向此终端发出get请求时,则会请求到用户预先定义的`findAll`方法。这个方法会返回status code(状态码)为200的相关的响应,在这里就是一个字符串。这是如何发生的?为了解释,我们首先介绍Nest采用两种不同选择来操纵响应的概念: + +- **Standard 标准式** + 这种模式下,当一个handler(处理器)内部返回一个JS对象或者数组,将自动将其转换为JSON。当返回JS的原生类型(String Number Boolean etc...),Nest不会做任何处理。 + + 此外StatusCode一般都是200,除了POST请求使用201。我们可以改变这个行为通过`@HttpCode()`装饰器。 +- **Library-specific 具体库模式** + 我们可以使用具体的库的(eg,Express)响应对象。可以在handler的签名上使用`@Res()`装饰器 `(e.g., findAll(@Res() response))`.通过这种形式你可以使用被那个对象暴露的原生的响应处理方法。比如在Express中,你可这么写`response.status(200).send().` + +:::warning +当你使用@Res @Next装饰符的时候,NEST就认为你使用library-specific mode.此时standard mode就被禁用了。如果要同时使用这两种模式(比如通过注入对象只是去设置Cookie/headers,但是剩下的工作仍然交给框架)你必须设置`passthrough`为true. `@Res({ passthrough: true })` +::: + +## Request object (请求对象) + +handler通常需要访client请求数据。通常我们使用`@Req()`装饰器。 + +```js +import { Controller, Get, Req } from '@nestjs/common'; +import { Request } from 'express'; + +@Controller('cats') +export class CatsController { + @Get() + findAll(@Req() request: Request): string { + return 'This action returns all cats'; + } +} +``` + +:::tip +为了发挥express的类型优势,需要安装`@types/express` package。 +::: + +Request object不仅代表了HTTP请求而且有request query string, parameters, HTTP headers, 和 body [(read more here)](https://expressjs.com/en/api.html#req)这么多属性。一般情况下不需要你手动去获取他们。我们可以直接使用独立的装饰器比如`@Body() or @Query()` 下面是一些常用的装饰器列表 +![alt text](../images/decorator-list.png) + +为了兼容多基础平台(eg. express and fastify),Nest提供了`@Res @Response()` 装饰符`@Res`是`@Response`的别名。这两个都可以直接暴露原生的response对象。当使用原生对象的时候,你应该同时导入其TS类型,以发挥类型优势。注意当你在一个方法中注入@Res或@Response时,此时该Handler就变成了Library-specific mode,所以需要你去管理你自己的response. + +## Resources