[nuxt 3] (IX) server routing

Whether it's a house 、 Stars or deserts , Are beautiful because of invisible things ！ ———— 《 The little prince 》

Server routing

Nuxt Automatic scanning ~/server/api,~/server/routes, ~/server/middleware A file in a directory , To register Support API and Hot update of server handler .

Every file needs to pass defineEventHandler() Export a default function

The application can directly return JSON data , One Promise Or use event.res.end() To send a response

Example

Create a server/api/hello.ts file :

export default defineEventHandler((event) => {
  return {
    api: 'works'
  }
})

Limit what you can use await $fetch('/api/hello') To call this routinely API

Server routing

~/server/api The file in will automatically add a route prefix to the route /api If you don't want to add /api Prefix , You can put them in ~/server/routes In the folder .

Example :

export default defineEventHandler(() => 'Hello World!')

The above example , Can be routed /hello visit ,http://localhost:300/hello

Server side middleware

Nuxt Will automatically read ~/server/middleware The files in generate middleware for your project .

The middleware program will check the request before requesting other server routes , Expand , Header information , Record request , Extend the request object .

The middleware handler should not return any data （ Do not close or respond to requests ）, Just check or extend the request context , Or throw an exception .

Example :

export default defineEventHandler((event) => {
  console.log('New request: ' + event.req.url)
})

export default defineEventHandler((event) => {
  event.context.auth = { user: 123 }
})

Server assisted methods

Server routing is performed by unjs/h3 Empower , It provides a set of auxiliary methods .

::ReadMore{link="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers"} ::

You can ~/server/utils Add more auxiliary methods in .

Examples of use

Match route parameters

Server routing can use dynamic parameters such as /api/hello/[name].ts, And then through event.context.params To get .

Example:

export default defineEventHandler(event => `Hello, ${event.context.params.name}!`)

You can use await $feetch(‘/api/hello/nuxt’) request API , Then get Hello,nuxt!

matching HTPP Method

The request file name can be suffixed .get.post.put.delete To match the request HTTP Method.

export default defineEventHandler(() => 'Test get handler')

export default defineEventHandler(() => 'Test post handler')

The above example , Match to /test：

• GET method: return Test get handler
• POST method: return Test post handler
• other method: return 404 error

Capture all routes

Capturing all routes helps to fallback route processing , for example , Create a name that is ～/server/api/foo/[...].ts The file of , Will register a capture all routes , Used to match routes that do not match , such as /api/foo/bar/baz

Example :

export default defineEventHandler(() => `Default foo handler`)

export default defineEventHandler(() => `Default api handler`)

Use body To process requests

export default defineEventHandler(async (event) => {
    const body = await useBody(event)
    return { body }
})

Now you can use fetch('/api/submit', { method: 'post', body: { test: 123 } }) Way to call this API.

We are in the file name submit.post.ts Match post Method to get the request body , If in a get Use... In request useBody, Will throw out a HTTP error 405 method Not Allowed.

Use query To process requests

ordinary query /api/query?param1=a&param2=b

export default defineEventHandler((event) => {
  const query = useQuery(event)
  return { a: query.param1, b: query.param2 }
})

Get the configuration of the runtime

export default defineEventHandler((event) => {
  const config = useRuntimeConfig()
  return { key: config.KEY }
})

Obtain requested cookie

export default defineEventHandler((event) => {
  const cookies = useCookies(event)
  return { cookies }
})

Advanced usage example

Use nested routing

import { createRouter } from 'h3'

const router = createRouter()

router.get('/', () => 'Hello World')

export default router

Sending data streams ( Experimental stage )

Be careful : It's an experimental feature , Only in Nodejs Use in the environment .

import fs from 'node:fs'
import { sendStream } from 'h3'

export default defineEventHandler((event) => {
  return sendStream(event, fs.createReadStream('/path/to/file'))
})

Return to a traditional handler or middleware

export default (req, res) => {
  res.end('Legacy handler')
}

Use unjs/h3 Can support traditional support , But it suggests that you avoid using traditional methods as much as possible .

export default (req, res, next) => {
  console.log('Legacy middleware')
  next()
}

Never will next() Callback and async Or return Promise With traditional middleware .