【node.js】实战项目

个人主页：Guiat
归属专栏：node.js

正文

1. 项目概览与架构设计

1.1 实战项目：企业级电商管理系统

我们将构建一个完整的企业级电商管理系统，包含用户管理、商品管理、订单处理、支付系统、库存管理等核心功能。

1.2 技术栈选择

2. 项目初始化与基础架构

2.1 项目结构设计

ecommerce-system/
├── 1-services/                 # 微服务目录
│   ├── user-service/          # 用户服务
│   ├── product-service/       # 商品服务
│   ├── order-service/         # 订单服务
│   ├── payment-service/       # 支付服务
│   ├── inventory-service/     # 库存服务
│   └── notification-service/  # 通知服务
├── 2-shared/                  # 共享模块
│   ├── database/             # 数据库配置
│   ├── middleware/           # 中间件
│   ├── utils/               # 工具函数
│   └── types/               # 类型定义
├── 3-gateway/                # API网关
├── 4-config/                 # 配置文件
├── 5-scripts/                # 脚本文件
├── 6-tests/                  # 测试文件
├── 7-docs/                   # 文档
└── 8-deployment/             # 部署配置

2.2 基础配置管理

// 2-shared/config/index.js
const path = require('path');
const dotenv = require('dotenv');

// 1. 环境配置加载
const loadEnvironmentConfig = () => {
    const env = process.env.NODE_ENV || 'development';
    const envFile = path.join(__dirname, `../../4-config/.env.${env}`);
    
    dotenv.config({ path: envFile });
    
    return {
        env,
        port: parseInt(process.env.PORT) || 3000,
        host: process.env.HOST || 'localhost'
    };
};

// 2. 数据库配置
const getDatabaseConfig = () => {
    return {
        mongodb: {
            uri: process.env.MONGODB_URI || 'mongodb://localhost:27017/ecommerce',
            options: {
                useNewUrlParser: true,
                useUnifiedTopology: true,
                maxPoolSize: 10,
                serverSelectionTimeoutMS: 5000,
                socketTimeoutMS: 45000,
            }
        },
        redis: {
            host: process.env.REDIS_HOST || 'localhost',
            port: parseInt(process.env.REDIS_PORT) || 6379,
            password: process.env.REDIS_PASSWORD,
            db: parseInt(process.env.REDIS_DB) || 0
        },
        mysql: {
            host: process.env.MYSQL_HOST || 'localhost',
            port: parseInt(process.env.MYSQL_PORT) || 3306,
            user: process.env.MYSQL_USER || 'root',
            password: process.env.MYSQL_PASSWORD,
            database: process.env.MYSQL_DATABASE || 'ecommerce'
        }
    };
};

// 3. 服务配置
const getServiceConfig = () => {
    return {
        userService: {
            url: process.env.USER_SERVICE_URL || 'http://localhost:3001',
            timeout: 5000
        },
        productService: {
            url: process.env.PRODUCT_SERVICE_URL || 'http://localhost:3002',
            timeout: 5000
        },
        orderService: {
            url: process.env.ORDER_SERVICE_URL || 'http://localhost:3003',
            timeout: 10000
        },
        paymentService: {
            url: process.env.PAYMENT_SERVICE_URL || 'http://localhost:3004',
            timeout: 15000
        },
        inventoryService: {
            url: process.env.INVENTORY_SERVICE_URL || 'http://localhost:3005',
            timeout: 5000
        },
        notificationService: {
            url: process.env.NOTIFICATION_SERVICE_URL || 'http://localhost:3006',
            timeout: 3000
        }
    };
};

// 4. 安全配置
const getSecurityConfig = () => {
    return {
        jwt: {
            secret: process.env.JWT_SECRET || 'your-secret-key',
            expiresIn: process.env.JWT_EXPIRES_IN || '24h',
            refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN || '7d'
        },
        bcrypt: {
            saltRounds: parseInt(process.env.BCRYPT_SALT_ROUNDS) || 12
        },
        cors: {
            origin: process.env.CORS_ORIGIN?.split(',') || ['http://localhost:3000'],
            credentials: true
        }
    };
};

// 5. 第三方服务配置
const getThirdPartyConfig = () => {
    return {
        email: {
            service: process.env.EMAIL_SERVICE || 'gmail',
            user: process.env.EMAIL_USER,
            password: process.env.EMAIL_PASSWORD
        },
        sms: {
            provider: process.env.SMS_PROVIDER || 'twilio',
            accountSid: process.env.TWILIO_ACCOUNT_SID,
            authToken: process.env.TWILIO_AUTH_TOKEN,
            phoneNumber: process.env.TWILIO_PHONE_NUMBER
        },
        payment: {
            stripe: {
                publicKey: process.env.STRIPE_PUBLIC_KEY,
                secretKey: process.env.STRIPE_SECRET_KEY,
                webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
            },
            paypal: {
                clientId: process.env.PAYPAL_CLIENT_ID,
                clientSecret: process.env.PAYPAL_CLIENT_SECRET,
                mode: process.env.PAYPAL_MODE || 'sandbox'
            }
        },
        storage: {
            aws: {
                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
                region: process.env.AWS_REGION || 'us-east-1',
                bucket: process.env.AWS_S3_BUCKET
            }
        }
    };
};

module.exports = {
    environment: loadEnvironmentConfig(),
    database: getDatabaseConfig(),
    services: getServiceConfig(),
    security: getSecurityConfig(),
    thirdParty: getThirdPartyConfig()
};

3. 用户服务实现

3.1 用户服务架构

3.2 用户模型设计

// 1-services/user-service/models/User.js
const mongoose = require('mongoose');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const { security } = require('../../../2-shared/config');

// 1. 用户基础信息模式
const userSchema = new mongoose.Schema({
    // 基本信息
    username: {
        type: String,
        required: true,
        unique: true,
        trim: true,
        minlength: 3,
        maxlength: 30,
        match: /^[a-zA-Z0-9_]+$/
    },
    email: {
        type: String,
        required: true,
        unique: true,
        trim: true,
        lowercase: true,
        match: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    },
    password: {
        type: String,
        required: true,
        minlength: 8,
        select: false // 默认不返回密码字段
    },
    
    // 个人信息
    profile: {
        firstName: { type: String, trim: true },
        lastName: { type: String, trim: true },
        avatar: { type: String },
        phone: { type: String, match: /^\+?[\d\s-()]+$/ },
        dateOfBirth: { type: Date },
        gender: { type: String, enum: ['male', 'female', 'other'] }
    },
    
    // 地址信息
    addresses: [{
        type: { type: String, enum: ['home', 'work', 'other'], default: 'home' },
        street: { type: String, required: true },
        city: { type: String, required: true },
        state: { type: String, required: true },
        zipCode: { type: String, required: true },
        country: { type: String, required: true },
        isDefault: { type: Boolean, default: false }
    }],
    
    // 账户状态
    status: {
        type: String,
        enum: ['active', 'inactive', 'suspended', 'deleted'],
        default: 'active'
    },
    emailVerified: { type: Boolean, default: false },
    phoneVerified: { type: Boolean, default: false },
    
    // 角色和权限
    roles: [{
        type: mongoose.Schema.Types.ObjectId,
        ref: 'Role'
    }],
    permissions: [{
        type: String
    }],
    
    // 安全信息
    lastLogin: { type: Date },
    loginAttempts: { type: Number, default: 0 },
    lockUntil: { type: Date },
    passwordResetToken: { type: String },
    passwordResetExpires: { type: Date },
    emailVerificationToken: { type: String },
    emailVerificationExpires: { type: Date },
    
    // 偏好设置
    preferences: {
        language: { type: String, default: 'en' },
        currency: { type: String, default: 'USD' },
        timezone: { type: String, default: 'UTC' },
        notifications: {
            email: { type: Boolean, default: true },
            sms: { type: Boolean, default: false },
            push: { type: Boolean, default: true }
        }
    },
    
    // 元数据
    metadata: {
        source: { type: String, default: 'web' }, // web, mobile, api
        referrer: { type: String },
        utmSource: { type: String },
        utmMedium: { type: String },
        utmCampaign: { type: String }
    }
}, {
    timestamps: true,
    toJSON: { virtuals: true },
    toObject: { virtuals: true }
});

// 2. 虚拟字段
userSchema.virtual('fullName').get(function() {
    return `${this.profile.firstName} ${this.profile.lastName}`.trim();
});

userSchema.virtual('isLocked').get(function() {
    return !!(this.lockUntil && this.lockUntil > Date.now());
});

// 3. 索引
userSchema.index({ email: 1 });
userSchema.index({ username: 1 });
userSchema.index({ 'profile.phone': 1 });
userSchema.index({ status: 1 });
userSchema.index({ createdAt: -1 });

// 4. 中间件
// 密码加密中间件
userSchema.pre('save', async function(next) {
    if (!this.isModified('password')) return next();
    
    try {
        const salt = await bcrypt.genSalt(security.bcrypt.saltRounds);
        this.password = await bcrypt.hash(this.password, salt);
        next();
    } catch (error) {
        next(error);
    }
});

// 5. 实例方法
// 密码验证
userSchema.methods.comparePassword = async function(candidatePassword) {
    return bcrypt.compare(candidatePassword, this.password);
};

// 生成JWT令牌
userSchema.methods.generateAuthToken = function() {
    const payload = {
        id: this._id,
        username: this.username,
        email: this.email,
        roles: this.roles
    };
    
    return jwt.sign(payload, security.jwt.secret, {
        expiresIn: security.jwt.expiresIn
    });
};

// 生成刷新令牌
userSchema.methods.generateRefreshToken = function() {
    const payload = {
        id: this._id,
        type: 'refresh'
    };
    
    return jwt.sign(payload, security.jwt.secret, {
        expiresIn: security.jwt.refreshExpiresIn
    });
};

// 增加登录尝试次数
userSchema.methods.incLoginAttempts = function() {
    // 如果之前有锁定且已过期，重置尝试次数
    if (this.lockUntil && this.lockUntil < Date.now()) {
        return this.updateOne({
            $unset: { lockUntil: 1 },
            $set: { loginAttempts: 1 }
        });
    }
    
    const updates = { $inc: { loginAttempts: 1 } };
    
    // 如果达到最大尝试次数且未锁定，则锁定账户
    if (this.loginAttempts + 1 >= 5 && !this.isLocked) {
        updates.$set = { lockUntil: Date.now() + 2 * 60 * 60 * 1000 }; // 锁定2小时
    }
    
    return this.updateOne(updates);
};

// 重置登录尝试
userSchema.methods.resetLoginAttempts = function() {
    return this.updateOne({
        $unset: { loginAttempts: 1, lockUntil: 1 }
    });
};

// 6. 静态方法
// 查找用户（支持邮箱或用户名）
userSchema.statics.findByCredentials = async function(identifier, password) {
    const user = await this.findOne({
        $or: [
            { email: identifier },
            { username: identifier }
        ],
        status: 'active'
    }).select('+password').populate('roles');
    
    if (!user) {
        throw new Error('Invalid credentials');
    }
    
    if (user.isLocked) {
        throw new Error('Account is temporarily locked');
    }
    
    const isMatch = await user.comparePassword(password);
    if (!isMatch) {
        await user.incLoginAttempts();
        throw new Error('Invalid credentials');
    }
    
    // 重置登录尝试并更新最后登录时间
    if (user.loginAttempts > 0) {
        await user.resetLoginAttempts();
    }
    
    user.lastLogin = new Date();
    await user.save();
    
    return user;
};

module.exports = mongoose.model('User', userSchema);

3.3 用户服务控制器

// 1-services/user-service/controllers/userController.js
const User = require('../models/User');
const { validationResult } = require('express-validator');
const crypto = require('crypto');
const { sendEmail } = require('../../../2-shared/utils/email');

class UserController {
    // 1. 用户注册
    async register(req, res) {
        try {
            // 验证输入
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const { username, email, password, profile } = req.body;

            // 检查用户是否已存在
            const existingUser = await User.findOne({
                $or: [{ email }, { username }]
            });

            if (existingUser) {
                return res.status(409).json({
                    success: false,
                    message: 'User already exists'
                });
            }

            // 创建新用户
            const user = new User({
                username,
                email,
                password,
                profile,
                emailVerificationToken: crypto.randomBytes(32).toString('hex'),
                emailVerificationExpires: Date.now() + 24 * 60 * 60 * 1000 // 24小时
            });

            await user.save();

            // 发送验证邮件
            await this.sendVerificationEmail(user);

            // 生成令牌
            const token = user.generateAuthToken();
            const refreshToken = user.generateRefreshToken();

            res.status(201).json({
                success: true,
                message: 'User registered successfully',
                data: {
                    user: {
                        id: user._id,
                        username: user.username,
                        email: user.email,
                        profile: user.profile,
                        emailVerified: user.emailVerified
                    },
                    tokens: {
                        accessToken: token,
                        refreshToken
                    }
                }
            });
        } catch (error) {
            console.error('Registration error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 2. 用户登录
    async login(req, res) {
        try {
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const { identifier, password } = req.body;

            // 验证用户凭据
            const user = await User.findByCredentials(identifier, password);

            // 生成令牌
            const token = user.generateAuthToken();
            const refreshToken = user.generateRefreshToken();

            // 记录登录日志
            await this.logUserActivity(user._id, 'login', req);

            res.json({
                success: true,
                message: 'Login successful',
                data: {
                    user: {
                        id: user._id,
                        username: user.username,
                        email: user.email,
                        profile: user.profile,
                        roles: user.roles,
                        emailVerified: user.emailVerified
                    },
                    tokens: {
                        accessToken: token,
                        refreshToken
                    }
                }
            });
        } catch (error) {
            console.error('Login error:', error);
            res.status(401).json({
                success: false,
                message: error.message || 'Login failed'
            });
        }
    }

    // 3. 获取用户信息
    async getProfile(req, res) {
        try {
            const user = await User.findById(req.user.id)
                .populate('roles')
                .select('-password');

            if (!user) {
                return res.status(404).json({
                    success: false,
                    message: 'User not found'
                });
            }

            res.json({
                success: true,
                data: { user }
            });
        } catch (error) {
            console.error('Get profile error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 4. 更新用户信息
    async updateProfile(req, res) {
        try {
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const updates = req.body;
            const allowedUpdates = ['profile', 'preferences', 'addresses'];
            const actualUpdates = {};

            // 过滤允许的更新字段
            Object.keys(updates).forEach(key => {
                if (allowedUpdates.includes(key)) {
                    actualUpdates[key] = updates[key];
                }
            });

            const user = await User.findByIdAndUpdate(
                req.user.id,
                actualUpdates,
                { new: true, runValidators: true }
            ).select('-password');

            if (!user) {
                return res.status(404).json({
                    success: false,
                    message: 'User not found'
                });
            }

            res.json({
                success: true,
                message: 'Profile updated successfully',
                data: { user }
            });
        } catch (error) {
            console.error('Update profile error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 5. 修改密码
    async changePassword(req, res) {
        try {
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const { currentPassword, newPassword } = req.body;

            const user = await User.findById(req.user.id).select('+password');
            if (!user) {
                return res.status(404).json({
                    success: false,
                    message: 'User not found'
                });
            }

            // 验证当前密码
            const isCurrentPasswordValid = await user.comparePassword(currentPassword);
            if (!isCurrentPasswordValid) {
                return res.status(400).json({
                    success: false,
                    message: 'Current password is incorrect'
                });
            }

            // 更新密码
            user.password = newPassword;
            await user.save();

            res.json({
                success: true,
                message: 'Password changed successfully'
            });
        } catch (error) {
            console.error('Change password error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 6. 邮箱验证
    async verifyEmail(req, res) {
        try {
            const { token } = req.params;

            const user = await User.findOne({
                emailVerificationToken: token,
                emailVerificationExpires: { $gt: Date.now() }
            });

            if (!user) {
                return res.status(400).json({
                    success: false,
                    message: 'Invalid or expired verification token'
                });
            }

            user.emailVerified = true;
            user.emailVerificationToken = undefined;
            user.emailVerificationExpires = undefined;
            await user.save();

            res.json({
                success: true,
                message: 'Email verified successfully'
            });
        } catch (error) {
            console.error('Email verification error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 7. 发送验证邮件
    async sendVerificationEmail(user) {
        const verificationUrl = `${process.env.FRONTEND_URL}/verify-email/${user.emailVerificationToken}`;
        
        await sendEmail({
            to: user.email,
            subject: 'Verify Your Email Address',
            template: 'email-verification',
            data: {
                username: user.username,
                verificationUrl
            }
        });
    }

    // 8. 记录用户活动
    async logUserActivity(userId, action, req) {
        // 这里可以记录到数据库或日志系统
        console.log(`User ${userId} performed ${action} from ${req.ip}`);
    }
}

module.exports = new UserController();

4. 商品服务实现

4.1 商品服务数据流

4.2 商品模型设计

// 1-services/product-service/models/Product.js
const mongoose = require('mongoose');

// 1. 商品规格模式
const specificationSchema = new mongoose.Schema({
    name: { type: String, required: true },
    value: { type: String, required: true },
    unit: { type: String },
    order: { type: Number, default: 0 }
});

// 2. 商品变体模式
const variantSchema = new mongoose.Schema({
    sku: { type: String, required: true, unique: true },
    attributes: [{
        name: { type: String, required: true },
        value: { type: String, required: true }
    }],
    price: {
        base: { type: Number, required: true },
        sale: { type: Number },
        cost: { type: Number }
    },
    inventory: {
        quantity: { type: Number, default: 0 },
        reserved: { type: Number, default: 0 },
        available: { type: Number, default: 0 },
        lowStockThreshold: { type: Number, default: 10 }
    },
    images: [{ type: String }],
    weight: { type: Number },
    dimensions: {
        length: { type: Number },
        width: { type: Number },
        height: { type: Number }
    },
    status: {
        type: String,
        enum: ['active', 'inactive', 'out_of_stock'],
        default: 'active'
    }
});

// 3. 主商品模式
const productSchema = new mongoose.Schema({
    // 基本信息
    name: { type: String, required: true, trim: true },
    slug: { type: String, required: true, unique: true },
    description: { type: String, required: true },
    shortDescription: { type: String },
    
    // 分类信息
    category: {
        type: mongoose.Schema.Types.ObjectId,
        ref: 'Category',
        required: true
    },
    subcategories: [{
        type: mongoose.Schema.Types.ObjectId,
        ref: 'Category'
    }],
    tags: [{ type: String }],
    
    // 品牌信息
    brand: {
        type: mongoose.Schema.Types.ObjectId,
        ref: 'Brand'
    },
    
    // 媒体资源
    images: [{
        url: { type: String, required: true },
        alt: { type: String },
        order: { type: Number, default: 0 },
        isMain: { type: Boolean, default: false }
    }],
    videos: [{
        url: { type: String },
        title: { type: String },
        duration: { type: Number }
    }],
    
    // 商品规格
    specifications: [specificationSchema],
    
    // 商品变体
    variants: [variantSchema],
    
    // 价格信息（基础价格，如果没有变体）
    price: {
        base: { type: Number },
        sale: { type: Number },
        cost: { type: Number },
        currency: { type: String, default: 'USD' }
    },
    
    // 库存信息（如果没有变体）
    inventory: {
        quantity: { type: Number, default: 0 },
        reserved: { type: Number, default: 0 },
        available: { type: Number, default: 0 },
        lowStockThreshold: { type: Number, default: 10 },
        trackQuantity: { type: Boolean, default: true }
    },
    
    // 物理属性
    weight: { type: Number },
    dimensions: {
        length: { type: Number },
        width: { type: Number },
        height: { type: Number },
        unit: { type: String, default: 'cm' }
    },
    
    // 状态信息
    status: {
        type: String,
        enum: ['draft', 'active', 'inactive', 'archived'],
        default: 'draft'
    },
    visibility: {
        type: String,
        enum: ['public', 'private', 'hidden'],
        default: 'public'
    },
    
    // SEO信息
    seo: {
        title: { type: String },
        description: { type: String },
        keywords: [{ type: String }],
        canonicalUrl: { type: String }
    },
    
    // 销售信息
    sales: {
        totalSold: { type: Number, default: 0 },
        totalRevenue: { type: Number, default: 0 },
        averageRating: { type: Number, default: 0 },
        reviewCount: { type: Number, default: 0 }
    },
    
    // 配送信息
    shipping: {
        weight: { type: Number },
        requiresShipping: { type: Boolean, default: true },
        shippingClass: { type: String },
        freeShipping: { type: Boolean, default: false }
    },
    
    // 税务信息
    tax: {
        taxable: { type: Boolean, default: true },
        taxClass: { type: String, default: 'standard' }
    },
    
    // 元数据
    metadata: {
        vendor: { type: String },
        manufacturerPartNumber: { type: String },
        gtin: { type: String }, // Global Trade Item Number
        condition: {
            type: String,
            enum: ['new', 'used', 'refurbished'],
            default: 'new'
        }
    },
    
    // 时间戳
    publishedAt: { type: Date },
    featuredUntil: { type: Date }
}, {
    timestamps: true,
    toJSON: { virtuals: true },
    toObject: { virtuals: true }
});

// 4. 虚拟字段
productSchema.virtual('isOnSale').get(function() {
    if (this.variants && this.variants.length > 0) {
        return this.variants.some(variant => variant.price.sale && variant.price.sale < variant.price.base);
    }
    return this.price.sale && this.price.sale < this.price.base;
});

productSchema.virtual('minPrice').get(function() {
    if (this.variants && this.variants.length > 0) {
        const prices = this.variants.map(v => v.price.sale || v.price.base);
        return Math.min(...prices);
    }
    return this.price.sale || this.price.base;
});

productSchema.virtual('maxPrice').get(function() {
    if (this.variants && this.variants.length > 0) {
        const prices = this.variants.map(v => v.price.sale || v.price.base);
        return Math.max(...prices);
    }
    return this.price.sale || this.price.base;
});

productSchema.virtual('totalInventory').get(function() {
    if (this.variants && this.variants.length > 0) {
        return this.variants.reduce((total, variant) => total + variant.inventory.available, 0);
    }
    return this.inventory.available;
});

// 5. 索引
productSchema.index({ name: 'text', description: 'text', tags: 'text' });
productSchema.index({ slug: 1 });
productSchema.index({ category: 1 });
productSchema.index({ brand: 1 });
productSchema.index({ status: 1 });
productSchema.index({ 'price.base': 1 });
productSchema.index({ 'sales.totalSold': -1 });
productSchema.index({ 'sales.averageRating': -1 });
productSchema.index({ createdAt: -1 });
productSchema.index({ publishedAt: -1 });

// 6. 中间件
// 生成slug
productSchema.pre('save', function(next) {
    if (this.isModified('name') && !this.slug) {
        this.slug = this.name
            .toLowerCase()
            .replace(/[^a-z0-9]+/g, '-')
            .replace(/(^-|-$)/g, '');
    }
    next();
});

// 更新可用库存
productSchema.pre('save', function(next) {
    if (this.variants && this.variants.length > 0) {
        this.variants.forEach(variant => {
            variant.inventory.available = Math.max(0, variant.inventory.quantity - variant.inventory.reserved);
        });
    } else {
        this.inventory.available = Math.max(0, this.inventory.quantity - this.inventory.reserved);
    }
    next();
});

// 7. 实例方法
// 检查库存
productSchema.methods.checkStock = function(variantId, quantity = 1) {
    if (variantId) {
        const variant = this.variants.id(variantId);
        return variant && variant.inventory.available >= quantity;
    }
    return this.inventory.available >= quantity;
};

// 预留库存
productSchema.methods.reserveStock = async function(variantId, quantity) {
    if (variantId) {
        const variant = this.variants.id(variantId);
        if (variant && variant.inventory.available >= quantity) {
            variant.inventory.reserved += quantity;
            await this.save();
            return true;
        }
    } else if (this.inventory.available >= quantity) {
        this.inventory.reserved += quantity;
        await this.save();
        return true;
    }
    return false;
};

// 释放库存
productSchema.methods.releaseStock = async function(variantId, quantity) {
    if (variantId) {
        const variant = this.variants.id(variantId);
        if (variant) {
            variant.inventory.reserved = Math.max(0, variant.inventory.reserved - quantity);
            await this.save();
        }
    } else {
        this.inventory.reserved = Math.max(0, this.inventory.reserved - quantity);
        await this.save();
    }
};

// 8. 静态方法
// 搜索商品
productSchema.statics.search = function(query, options = {}) {
    const {
        category,
        brand,
        minPrice,
        maxPrice,
        inStock,
        sort = '-createdAt',
        page = 1,
        limit = 20
    } = options;

    const filter = {
        status: 'active',
        visibility: 'public'
    };

    if (query) {
        filter.$text = { $search: query };
    }

    if (category) {
        filter.category = category;
    }

    if (brand) {
        filter.brand = brand;
    }

    if (minPrice || maxPrice) {
        filter['price.base'] = {};
        if (minPrice) filter['price.base'].$gte = minPrice;
        if (maxPrice) filter['price.base'].$lte = maxPrice;
    }

    if (inStock) {
        filter['inventory.available'] = { $gt: 0 };
    }

    const skip = (page - 1) * limit;

    return this.find(filter)
        .populate('category brand')
        .sort(sort)
        .skip(skip)
        .limit(limit);
};

module.exports = mongoose.model('Product', productSchema);

4.3 商品服务控制器

// 1-services/product-service/controllers/productController.js
const Product = require('../models/Product');
const Category = require('../models/Category');
const { validationResult } = require('express-validator');
const { uploadToS3, deleteFromS3 } = require('../../../2-shared/utils/storage');

class ProductController {
    // 1. 创建商品
    async createProduct(req, res) {
        try {
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const productData = req.body;
            
            // 验证分类是否存在
            const category = await Category.findById(productData.category);
            if (!category) {
                return res.status(400).json({
                    success: false,
                    message: 'Invalid category'
                });
            }

            // 处理图片上传
            if (req.files && req.files.length > 0) {
                const imageUrls = await Promise.all(
                    req.files.map(async (file, index) => {
                        const url = await uploadToS3(file, 'products');
                        return {
                            url,
                            alt: `${productData.name} image ${index + 1}`,
                            order: index,
                            isMain: index === 0
                        };
                    })
                );
                productData.images = imageUrls;
            }

            const product = new Product(productData);
            await product.save();

            await product.populate('category brand');

            res.status(201).json({
                success: true,
                message: 'Product created successfully',
                data: { product }
            });
        } catch (error) {
            console.error('Create product error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 2. 获取商品列表
    async getProducts(req, res) {
        try {
            const {
                page = 1,
                limit = 20,
                category,
                brand,
                minPrice,
                maxPrice,
                inStock,
                sort = '-createdAt',
                search
            } = req.query;

            const options = {
                category,
                brand,
                minPrice: minPrice ? parseFloat(minPrice) : undefined,
                maxPrice: maxPrice ? parseFloat(maxPrice) : undefined,
                inStock: inStock === 'true',
                sort,
                page: parseInt(page),
                limit: parseInt(limit)
            };

            const products = await Product.search(search, options);
            const total = await Product.countDocuments({
                status: 'active',
                visibility: 'public'
            });

            res.json({
                success: true,
                data: {
                    products,
                    pagination: {
                        page: parseInt(page),
                        limit: parseInt(limit),
                        total,
                        pages: Math.ceil(total / limit)
                    }
                }
            });
        } catch (error) {
            console.error('Get products error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 3. 获取单个商品
    async getProduct(req, res) {
        try {
            const { id } = req.params;

            const product = await Product.findOne({
                $or: [{ _id: id }, { slug: id }],
                status: 'active',
                visibility: 'public'
            }).populate('category brand');

            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            res.json({
                success: true,
                data: { product }
            });
        } catch (error) {
            console.error('Get product error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 4. 更新商品
    async updateProduct(req, res) {
        try {
            const errors = validationResult(req);
            if (!errors.isEmpty()) {
                return res.status(400).json({
                    success: false,
                    message: 'Validation failed',
                    errors: errors.array()
                });
            }

            const { id } = req.params;
            const updates = req.body;

            // 处理新上传的图片
            if (req.files && req.files.length > 0) {
                const newImages = await Promise.all(
                    req.files.map(async (file, index) => {
                        const url = await uploadToS3(file, 'products');
                        return {
                            url,
                            alt: `Product image ${index + 1}`,
                            order: index
                        };
                    })
                );
                
                // 合并现有图片和新图片
                if (updates.images) {
                    updates.images = [...updates.images, ...newImages];
                } else {
                    updates.images = newImages;
                }
            }

            const product = await Product.findByIdAndUpdate(
                id,
                updates,
                { new: true, runValidators: true }
            ).populate('category brand');

            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            res.json({
                success: true,
                message: 'Product updated successfully',
                data: { product }
            });
        } catch (error) {
            console.error('Update product error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 5. 删除商品
    async deleteProduct(req, res) {
        try {
            const { id } = req.params;

            const product = await Product.findById(id);
            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            // 删除关联的图片
            if (product.images && product.images.length > 0) {
                await Promise.all(
                    product.images.map(image => deleteFromS3(image.url))
                );
            }

            await Product.findByIdAndDelete(id);

            res.json({
                success: true,
                message: 'Product deleted successfully'
            });
        } catch (error) {
            console.error('Delete product error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 6. 检查库存
    async checkStock(req, res) {
        try {
            const { id } = req.params;
            const { variantId, quantity = 1 } = req.query;

            const product = await Product.findById(id);
            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            const inStock = product.checkStock(variantId, parseInt(quantity));

            res.json({
                success: true,
                data: {
                    inStock,
                    availableQuantity: variantId 
                        ? product.variants.id(variantId)?.inventory.available || 0
                        : product.inventory.available
                }
            });
        } catch (error) {
            console.error('Check stock error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 7. 预留库存
    async reserveStock(req, res) {
        try {
            const { id } = req.params;
            const { variantId, quantity } = req.body;

            const product = await Product.findById(id);
            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            const reserved = await product.reserveStock(variantId, quantity);

            if (!reserved) {
                return res.status(400).json({
                    success: false,
                    message: 'Insufficient stock'
                });
            }

            res.json({
                success: true,
                message: 'Stock reserved successfully'
            });
        } catch (error) {
            console.error('Reserve stock error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }

    // 8. 获取商品推荐
    async getRecommendations(req, res) {
        try {
            const { id } = req.params;
            const { limit = 10 } = req.query;

            const product = await Product.findById(id);
            if (!product) {
                return res.status(404).json({
                    success: false,
                    message: 'Product not found'
                });
            }

            // 基于分类和标签的推荐
            const recommendations = await Product.find({
                _id: { $ne: id },
                $or: [
                    { category: product.category },
                    { tags: { $in: product.tags } }
                ],
                status: 'active',
                visibility: 'public'
            })
            .populate('category brand')
            .sort({ 'sales.totalSold': -1 })
            .limit(parseInt(limit));

            res.json({
                success: true,
                data: { recommendations }
            });
        } catch (error) {
            console.error('Get recommendations error:', error);
            res.status(500).json({
                success: false,
                message: 'Internal server error'
            });
        }
    }
}

module.exports = new ProductController();

5. 订单服务实现

5.1 订单处理流程