koa3-demo/_backup_old_files/services/README.md

服务层 (Services)

本目录包含了应用的所有业务逻辑服务层，负责处理业务规则、数据验证和错误处理。

服务列表

1. UserService - 用户服务

处理用户相关的所有业务逻辑，包括用户注册、登录、密码管理等。

主要功能：

• 用户注册和登录
• 用户信息管理（增删改查）
• 密码加密和验证
• 用户统计和搜索
• 批量操作支持

使用示例：

import { userService } from '../services/index.js'

// 用户注册
const newUser = await userService.register({
    username: 'testuser',
    email: 'test@example.com',
    password: 'password123'
})

// 用户登录
const loginResult = await userService.login({
    username: 'testuser',
    password: 'password123'
})

2. ArticleService - 文章服务

处理文章相关的所有业务逻辑，包括文章的发布、编辑、搜索等。

主要功能：

• 文章的增删改查
• 文章状态管理（草稿/发布）
• 文章搜索和分类
• 阅读量统计
• 相关文章推荐
• 分页支持

使用示例：

import { articleService } from '../services/index.js'

// 创建文章
const article = await articleService.createArticle({
    title: '测试文章',
    content: '文章内容...',
    category: '技术',
    tags: 'JavaScript,Node.js'
})

// 获取已发布文章
const publishedArticles = await articleService.getPublishedArticles()

// 搜索文章
const searchResults = await articleService.searchArticles('JavaScript')

3. BookmarkService - 书签服务

处理用户书签的管理，包括添加、编辑、删除和搜索书签。

主要功能：

• 书签的增删改查
• URL格式验证
• 批量操作支持
• 书签统计和搜索
• 分页支持

使用示例：

import { bookmarkService } from '../services/index.js'

// 添加书签
const bookmark = await bookmarkService.createBookmark({
    user_id: 1,
    title: 'Google',
    url: 'https://www.google.com',
    description: '搜索引擎'
})

// 获取用户书签
const userBookmarks = await bookmarkService.getUserBookmarks(1)

// 搜索书签
const searchResults = await bookmarkService.searchUserBookmarks(1, 'Google')

4. SiteConfigService - 站点配置服务

管理站点的各种配置信息，如站点名称、描述、主题等。

主要功能：

• 配置的增删改查
• 配置值验证
• 批量操作支持
• 默认配置初始化
• 配置统计和搜索

使用示例：

import { siteConfigService } from '../services/index.js'

// 获取配置
const siteName = await siteConfigService.get('site_name')

// 设置配置
await siteConfigService.set('site_name', '我的新网站')

// 批量设置配置
await siteConfigService.setMany({
    'site_description': '网站描述',
    'posts_per_page': 20
})

// 初始化默认配置
await siteConfigService.initializeDefaultConfigs()

5. JobService - 任务服务

处理后台任务和定时任务的管理。

主要功能：

• 任务调度和管理
• 任务状态监控
• 任务日志记录

错误处理

所有服务都使用统一的错误处理机制：

import CommonError from 'utils/error/CommonError.js'

try {
    const result = await userService.getUserById(1)
} catch (error) {
    if (error instanceof CommonError) {
        // 业务逻辑错误
        console.error(error.message)
    } else {
        // 系统错误
        console.error('系统错误:', error.message)
    }
}

数据验证

服务层负责数据验证，确保数据的完整性和正确性：

• 输入验证：检查必填字段、格式验证等
• 业务验证：检查业务规则，如用户名唯一性
• 权限验证：确保用户只能操作自己的数据

事务支持

对于涉及多个数据库操作的方法，服务层支持事务处理：

// 在需要事务的方法中使用
async createUserWithProfile(userData, profileData) {
    // 这里可以添加事务支持
    const user = await this.createUser(userData)
    // 创建用户档案...
    return user
}

缓存策略

服务层可以集成缓存机制来提高性能：

// 示例：缓存用户信息
async getUserById(id) {
    const cacheKey = `user:${id}`
    let user = await cache.get(cacheKey)
    
    if (!user) {
        user = await UserModel.findById(id)
        await cache.set(cacheKey, user, 3600) // 缓存1小时
    }
    
    return user
}

使用建议

1. 控制器层调用服务：控制器应该调用服务层方法，而不是直接操作模型
2. 错误处理：在控制器中捕获服务层抛出的错误并返回适当的HTTP响应
3. 数据转换：服务层负责数据格式转换，控制器负责HTTP响应格式
4. 业务逻辑：复杂的业务逻辑应该放在服务层，保持控制器的简洁性

扩展指南

添加新的服务：

1. 创建新的服务文件（如 NewService.js）
2. 继承或实现基础服务接口
3. 在 index.js 中导出新服务
4. 添加相应的测试用例
5. 更新文档

// 新服务示例
class NewService {
    async doSomething(data) {
        try {
            // 业务逻辑
            return result
        } catch (error) {
            throw new CommonError(`操作失败: ${error.message}`)
        }
    }
}