Utils层设计

// src/utils/string.ts
 
/**
 * 将字符串转成 URL 友好的 slug 格式
 * "Hello World!" -> "hello-world"
 */
export function toSlug(input: string): string {
  return input
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')
    .replace(/[\s_]+/g, '-')
    .replace(/^-+|-+$/g, '')
}

// 这个函数依赖外部数据库，不是纯函数
export async function getUserCount(db: D1Database): Promise<number> {
  const result = await db.select({ count: sql<number>`count(*)` }).from(users)
  return result[0].count
}

// 这不是纯函数，因为每次调用结果不同
export function formatNow(): string {
  return new Date().toISOString().split('T')[0]
}

// 这是纯函数，相同输入永远返回相同输出
export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0]
}

// src/utils/date.ts
 
/**
 * Date 对象 -> YYYY-MM-DD 格式字符串
 */
export function formatDate(date: Date): string {
  const year = date.getFullYear()
  const month = String(date.getMonth() + 1).padStart(2, '0')
  const day = String(date.getDate()).padStart(2, '0')
  return `${year}-${month}-${day}`
}
 
/**
 * 判断一个日期字符串是否合法（YYYY-MM-DD 格式）
 */
export function isValidDate(dateString: string): boolean {
  const date = new Date(dateString)
  if (Number.isNaN(date.getTime())) return false
  // 回验：防止 new Date 自动修正不存在的日期（如 2026-02-30 -> 03-02）
  return formatDate(date) === dateString
}

// src/utils/string.ts
 
/**
 * 转 URL 友好的 slug
 * "Hello World!" -> "hello-world"
 */
export function toSlug(input: string): string {
  return input
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')
    .replace(/[\s_]+/g, '-')
    .replace(/^-+|-+$/g, '')
}
 
/**
 * 截断字符串到指定长度，超出部分用省略号替代
 */
export function truncate(input: string, maxLength: number): string {
  if (input.length <= maxLength) return input
  return `${input.slice(0, maxLength)}...`
}

// src/utils/type-convert.ts
 
/**
 * 安全地将字符串转为整数，转换失败返回默认值
 */
export function toInt(value: string, fallback = 0): number {
  const num = Number.parseInt(value, 10)
  return Number.isNaN(num) ? fallback : num
}
 
/**
 * 将常见的「真值字符串」转为布尔值
 * "true", "1", "yes" -> true
 * 其他 -> false
 */
export function toBoolean(value: string): boolean {
  return ['true', '1', 'yes'].includes(value.toLowerCase())
}
 
/**
 * 空字符串转为 null，否则原样返回
 * 用于处理前端传来的可选字段
 */
export function emptyToNull(value: string): string | null {
  return value.trim() === '' ? null : value
}

// src/utils/error.ts
 
/**
 * 应用级自定义错误
 * 携带 HTTP 状态码，方便错误处理中间件统一响应
 */
export class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
  ) {
    super(message)
    this.name = 'AppError'
  }
}
 
/**
 * 判断一个错误是否是 AppError 实例
 * 用于错误处理中间件区分业务错误和未知异常
 */
export function isAppError(error: unknown): error is AppError {
  return error instanceof AppError
}
 
/**
 * 404 快捷构造
 */
export function notFound(resource: string): AppError {
  return new AppError(404, 'NOT_FOUND', `${resource} 不存在`)
}
 
/**
 * 400 快捷构造
 */
export function badRequest(message: string): AppError {
  return new AppError(400, 'BAD_REQUEST', message)
}

// src/utils/response.ts
 
/**
 * 统一的分页响应格式
 */
export function paginatedResponse<T>(
  items: T[],
  total: number,
  page: number,
  pageSize: number,
) {
  return {
    code: 0,
    message: 'OK',
    data: {
      items,
      pagination: {
        total,
        page,
        pageSize,
        totalPages: Math.ceil(total / pageSize),
      },
    },
  }
}

// src/routes/posts.ts
app.get('/posts', async (c) => {
  const { items, total } = await fetchPosts(c)
  const page = toInt(c.req.query('page'), 1)
  const pageSize = toInt(c.req.query('pageSize'), 20)
 
  return c.json(paginatedResponse(items, total, page, pageSize))
})

import { formatDate } from '../../utils/date'
import { toSlug } from '../../utils/string'
import { toInt } from '../../utils/type-convert'

// src/utils/index.ts
export * from './date'
export * from './string'
export * from './type-convert'
export * from './error'
export * from './response'

import { formatDate, toSlug, toInt } from '../../utils'

// tests/utils/date.test.ts
import { describe, expect, it } from 'vitest'
import { formatDate, isValidDate } from '../../src/utils/date'
 
describe('formatDate', () => {
  it('格式化为 YYYY-MM-DD', () => {
    const date = new Date(2026, 5, 20) // 月份从 0 开始，5 = 六月
    expect(formatDate(date)).toBe('2026-06-20')
  })
 
  it('个位数月份和日期补零', () => {
    const date = new Date(2026, 0, 5)
    expect(formatDate(date)).toBe('2026-01-05')
  })
})
 
describe('isValidDate', () => {
  it('接受合法日期字符串', () => {
    expect(isValidDate('2026-06-20')).toBe(true)
  })
 
  it('拒绝非日期字符串', () => {
    expect(isValidDate('not-a-date')).toBe(false)
  })
 
  it('拒绝被自动修正的日期', () => {
    // 2026-02-30 不存在，new Date 会修正为 03-02
    expect(isValidDate('2026-02-30')).toBe(false)
  })
})