响应

import router from '@adonisjs/core/services/router'

router.get('/', async () => {
  /**
   * 返回纯文本，content-type: text/plain
   */
  return 'This is the homepage.'
})

router.get('/welcome', async () => {
  /**
   * 返回 HTML 片段，content-type: text/html
   */
  return '<p>This is the homepage</p>'
})

router.get('/api/page', async () => {
  /**
   * 返回 JSON，content-type: application/json
   */
  return { page: 'home' }
})

router.get('/timestamp', async () => {
  /**
   * Date 实例会被转换为 ISO 字符串
   */
  return new Date()
})

import router from '@adonisjs/core/services/router'

router.get('/', async ({ response }) => {
  /**
   * send() 方法与返回值的工作方式完全相同。
   * 当你需要在发送前设置请求头或状态时很有用。
   */
  response.send('This is the homepage')
})

router.get('/data', async ({ response }) => {
  /**
   * 对象和数组会自动被字符串化
   */
  response.send({ page: 'home' })
})

import Post from '#models/post'
import type { HttpContext } from '@adonisjs/core/http'

export default class PostsController {
  async index({ response }: HttpContext) {
    const posts = await Post.all()
    
    /**
     * 显式将 content-type 设置为 application/json
     * 并序列化 posts 数组
     */
    response.json(posts)
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class ApiController {
  async index({ response }: HttpContext) {
    /**
     * 设置用于 API 版本控制的自定义请求头
     */
    response.header('X-API-Version', 'v1')
    
    /**
     * 设置缓存控制请求头
     */
    response.header('Cache-Control', 'public, max-age=3600')
    
    return { status: 'ok' }
  }
}

import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class CorsMiddleware {
  async handle({ response }: HttpContext, next: NextFn) {
    /**
     * 仅当其他中间件尚未设置时才设置 CORS 请求头
     */
    response.safeHeader('Access-Control-Allow-Origin', '*')
    
    await next()
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class DownloadsController {
  async show({ response }: HttpContext) {
    /**
     * 为不同的 Cookie 追加多个 Set-Cookie 请求头
     */
    response.append('Set-Cookie', 'session=abc123; HttpOnly')
    response.append('Set-Cookie', 'preferences=dark-mode; Path=/')
    
    return { download: 'ready' }
  }
}

import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class SecurityMiddleware {
  async handle({ response }: HttpContext, next: NextFn) {
    await next()
    
    /**
     * 移除 server 请求头以隐藏服务器实现细节
     */
    response.removeHeader('X-Powered-By')
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class AuthController {
  async logout({ response, auth }: HttpContext) {
    await auth.logout()
    
    /**
     * 退出登录后重定向到主页
     */
    response.redirect().toPath('/')
  }
  
  async external({ response }: HttpContext) {
    /**
     * 重定向到外部网站
     */
    response.redirect().toPath('https://adonisjs.com')
  }
}

import Post from '#models/post'
import { createPostValidator } from '#validators/post'
import type { HttpContext } from '@adonisjs/core/http'

export default class PostsController {
  async store({ request, response }: HttpContext) {
    /**
     * 验证传入的请求数据
     */
    const payload = await request.validateUsing(createPostValidator)
    
    /**
     * 创建文章
     */
    const post = await Post.create(payload)
    
    /**
     * 重定向到新创建文章的展示页面
     */
    response.redirect().toRoute('posts.show', [post.id])
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class CommentsController {
  async destroy({ response, params }: HttpContext) {
    /**
     * 重定向回用户来源的页面。
     * 如果找不到有效的引用来源，则回退到 /posts。
     */
    response.redirect().back('/posts')
  }
}

import { defineConfig } from '@adonisjs/core/http'

export const http = defineConfig({
  redirect: {
    allowedHosts: [
      'app.example.com',
      'admin.example.com',
    ],
  },
})

import type { HttpContext } from '@adonisjs/core/http'

export default class AuthController {
  async redirectToProvider({ session, response }: HttpContext) {
    /**
     * 存储当前 URL，以便在 OAuth 流程完成之后
     * back() 返回到这里
     */
    session.put('redirect.previousUrl', '/dashboard')
    response.redirect().toPath('https://accounts.google.com/o/oauth2/auth')
  }

  async handleCallback({ response }: HttpContext) {
    /**
     * 这将重定向到 /dashboard（来自会话）
     * 而不是使用 Referer 请求头
     */
    response.redirect().back()
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class PagesController {
  async oldPage({ response }: HttpContext) {
    /**
     * 为已移动的页面使用永久重定向（301）
     */
    response.redirect().status(301).toPath('/new-page')
  }
}

import { defineConfig } from '@adonisjs/core/http'

export const http = defineConfig({
  redirect: {
    forwardQueryString: true,
  },
})

import type { HttpContext } from '@adonisjs/core/http'

export default class AuthController {
  async logout({ response }: HttpContext) {
    /**
     * 禁用此重定向的查询字符串转发。
     * 用户将被发送到 /，不带任何查询参数。
     */
    response.redirect().withQs(false).toPath('/')
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class SearchController {
  async filter({ response }: HttpContext) {
    /**
     * 将现有的查询参数转发到新 URL。
     * 如果当前 URL 是 /search?q=adonis&sort=date，
     * 这将重定向到 /results?q=adonis&sort=date
     */
    response.redirect().withQs().toPath('/results')
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class ProductsController {
  async search({ response }: HttpContext) {
    /**
     * 使用自定义查询参数重定向。
     * 结果为 /products?category=electronics&sort=price
     */
    response
      .redirect()
      .withQs({ category: 'electronics' })
      .withQs({ sort: 'price' })
      .toPath('/products')
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class SessionController {
  async store({ auth, request, response }: HttpContext) {
    await auth.use('web').login(
      await User.verifyCredentials(
        request.input('email'),
        request.input('password')
      )
    )

    /**
     * 重定向到预期 URL 或 /dashboard
     */
    return response.redirect().toIntended('/dashboard')
  }
}

import { createReadStream } from 'node:fs'
import type { HttpContext } from '@adonisjs/core/http'

export default class ExportsController {
  async generate({ response }: HttpContext) {
    /**
     * 从文件创建一个可读流
     */
    const stream = createReadStream('./exports/data.csv')
    
    /**
     * 将文件流式传输给客户端。
     * AdonisJS 自动处理背压和清理。
     */
    response.stream(stream)
  }
}

import app from '@adonisjs/core/services/app'
import type { HttpContext } from '@adonisjs/core/http'

export default class InvoicesController {
  async download({ response, params }: HttpContext) {
    /**
     * 构建指向发票文件的绝对路径
     */
    const filePath = app.makePath(`storage/invoices/${params.id}.pdf`)
    
    /**
     * 流式传输文件以供下载，并支持 ETag。
     * 只要文件内容保持不变，浏览器就会缓存该响应。
     */
    response.download(filePath)
  }
}

import app from '@adonisjs/core/services/app'
import type { HttpContext } from '@adonisjs/core/http'

export default class ReportsController {
  async export({ response, params }: HttpContext) {
    /**
     * 指向报表文件的绝对路径
     */
    const filePath = app.makePath(`storage/reports/${params.id}.xlsx`)
    
    /**
     * 以用户友好的文件名强制下载。
     * 第二个参数在 Content-Disposition 请求头中设置文件名。
     */
    response.attachment(filePath, `monthly-report-${params.month}.xlsx`)
  }
}

import Post from '#models/post'
import type { HttpContext } from '@adonisjs/core/http'

export default class PostsController {
  async store({ request, response }: HttpContext) {
    const post = await Post.create(request.all())
    
    /**
     * 成功创建资源时返回 201 Created
     */
    response.status(201)
    
    return post
  }
}

import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class JsonApiMiddleware {
  async handle({ response }: HttpContext, next: NextFn) {
    await next()
    
    /**
     * 仅在尚未设置时才设置默认的成功状态。
     * 控制器特定的状态码优先。
     */
    response.safeStatus(200)
  }
}

import User from '#models/user'
import type { HttpContext } from '@adonisjs/core/http'

export default class UsersController {
  async show({ response, params }: HttpContext) {
    const user = await User.find(params.id)
    
    if (!user) {
      /**
       * 一次调用中设置状态 404 并发送响应体
       */
      return response.notFound({ error: 'User not found' })
    }
    
    return user
  }
  
  async destroy({ response, params, auth }: HttpContext) {
    const user = await User.findOrFail(params.id)
    
    if (user.id !== auth.user.id) {
      /**
       * 设置状态 403 并发送错误消息
       */
      return response.forbidden({ error: 'Cannot delete other users' })
    }
    
    await user.delete()
    return response.noContent()
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class PreferencesController {
  async update({ response, request }: HttpContext) {
    const theme = request.input('theme')
    
    /**
     * 设置一个 2 小时后过期的签名 Cookie。
     * 签名可防止客户端篡改。
     */
    response.cookie('theme', theme, {
      maxAge: '2h'
    })
    
    return { success: true }
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class SessionsController {
  async create({ response, auth }: HttpContext) {
    /**
     * 将敏感的会话数据存储在加密 Cookie 中。
     * 该值使用 app.appKey 加密。
     */
    response.encryptedCookie('session_data', {
      userId: auth.user.id,
      loginAt: new Date()
    })
    
    return { success: true }
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class TrackingController {
  async view({ response }: HttpContext) {
    /**
     * 为非敏感的追踪数据设置普通 Cookie
     */
    response.plainCookie('last_visit', new Date().toISOString())
    
    return { success: true }
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class CartController {
  async add({ response, request }: HttpContext) {
    const cartItems = [
      { id: 1, name: 'Product A', quantity: 2 },
      { id: 2, name: 'Product B', quantity: 1 }
    ]
    
    /**
     * 数组和对象会被自动序列化
     */
    response.encryptedCookie('cart', cartItems)
    
    return { success: true }
  }
}

import type { HttpContext } from '@adonisjs/core/http'

export default class AuthController {
  async login({ response, auth }: HttpContext) {
    /**
     * 设置带有安全选项的认证 Cookie
     */
    response.encryptedCookie('auth_token', auth.token, {
      domain: '',
      path: '/',
      maxAge: '2h',
      httpOnly: true,      // 阻止 JavaScript 访问
      secure: true,        // 仅通过 HTTPS 发送
      sameSite: 'lax',     // CSRF 防护
      partitioned: false,  // 实验性：CHIPS
      priority: 'medium'   // 实验性：Cookie 优先级
    })
    
    return { success: true }
  }
}

import { unlink } from 'node:fs/promises'
import app from '@adonisjs/core/services/app'
import type { HttpContext } from '@adonisjs/core/http'

export default class FilesController {
  async download({ response, params }: HttpContext) {
    const filePath = app.makePath(`tmp/exports/${params.id}.zip`)
    
    /**
     * 在流式传输文件之前注册清理回调
     */
    response.onFinish(async () => {
      await unlink(filePath)
    })
    
    /**
     * 流式传输文件。下载完成后，
     * 清理回调将自动运行。
     */
    response.download(filePath)
  }
}

import type { HttpContext } from '@adonisjs/core/http'
import type { NextFn } from '@adonisjs/core/types/http'

export default class AnalyticsMiddleware {
  async handle({ response, request }: HttpContext, next: NextFn) {
    const startTime = Date.now()
    
    /**
     * 在响应发送后注册分析日志记录。
     * 这不会延迟对客户端响应。
     */
    response.onFinish(() => {
      const duration = Date.now() - startTime
      console.log(`${request.method()} ${request.url()} - ${duration}ms`)
    })
    
    await next()
  }
}

import router from '@adonisjs/core/services/router'

router.get('/api/data', async () => {
  /**
   * 返回 content-type: application/json 的 JSON
   * BigInt 值会被安全地序列化为字符串
   */
  return {
    id: BigInt(9007199254740991),
    timestamp: new Date(),
    active: true
  }
})

router.get('/page', async () => {
  /**
   * 返回 content-type: text/html 的 HTML
   */
  return '<h1>Welcome</h1>'
})

router.get('/text', async () => {
  /**
   * 返回 content-type: text/plain 的纯文本
   */
  return 'Hello, world!'
})

import { HttpResponse } from '@adonisjs/core/http'

export default class AppProvider {
  async boot() {
    /**
     * 添加一个自定义方法，以一致的结构发送 API 响应
     */
    HttpResponse.macro('api', function (data: any, meta?: Record<string, any>) {
      return this.json({
        success: true,
        data: data,
        meta: meta || {}
      })
    })
    
    /**
     * 添加一个用于分页响应的自定义方法
     */
    HttpResponse.macro('paginated', function (items: any[], pagination: any) {
      return this.json({
        data: items,
        pagination: {
          page: pagination.page,
          perPage: pagination.perPage,
          total: pagination.total
        }
      })
    })
  }
}

import { HttpResponse } from '@adonisjs/core/http'

declare module '@adonisjs/core/http' {
  export interface HttpResponse {
    /**
     * 发送标准化的 API 响应
     */
    api(data: any, meta?: Record<string, any>): void
    
    /**
     * 发送分页响应
     */
    paginated(items: any[], pagination: {
      page: number
      perPage: number
      total: number
    }): void
  }
}

import Post from '#models/post'
import type { HttpContext } from '@adonisjs/core/http'

export default class PostsController {
  async index({ response }: HttpContext) {
    const posts = await Post.all()
    
    /**
     * 使用自定义 api() 方法获得一致的响应
     */
    return response.api(posts, {
      version: 'v1',
      timestamp: new Date()
    })
  }
  
  async paginated({ response, request }: HttpContext) {
    const page = request.input('page', 1)
    const posts = await Post.query().paginate(page, 20)
    
    /**
     * 使用自定义 paginated() 方法
     */
    return response.paginated(posts.all(), posts.getMeta())
  }
}