TypeScript参数装饰器：为方法参数添加额外功能

什么是 TypeScript 参数装饰器

在 TypeScript 中，装饰器是一种特殊类型的声明，它能够被附加到类声明、方法、访问器、属性或参数上。参数装饰器主要应用于方法的参数，其作用是为这些参数添加额外的功能或者行为。参数装饰器表达式会在运行时当作函数被调用，并且会传入一些特定的参数，我们可以基于这些参数来对目标参数进行操作。

参数装饰器的基本语法形式如下：

@decoratorExpression
function someFunction(parameter: any) {
    // 函数体
}

其中 @decoratorExpression 就是参数装饰器，它作用于 someFunction 函数的 parameter 参数上。

参数装饰器的使用场景

参数验证：在方法执行之前，通过参数装饰器对传入的参数进行验证。例如，确保一个参数是特定的类型或者在某个范围内。
日志记录：记录方法调用时传入的参数，方便调试和审计。
依赖注入：在方法调用时，通过参数装饰器注入所需的依赖。

深入理解参数装饰器的执行过程

参数装饰器函数接受三个参数：

target：对于静态成员来说是类的构造函数，对于实例成员是类的原型对象。
propertyKey：被装饰方法的名字。
parameterIndex：参数在方法参数列表中的索引位置。

以下是一个简单的示例，展示参数装饰器如何获取这些参数：

function logParameter(target: any, propertyKey: string, parameterIndex: number) {
    console.log(`Target: ${target.constructor.name}`);
    console.log(`Property Key: ${propertyKey}`);
    console.log(`Parameter Index: ${parameterIndex}`);
}

class MyClass {
    myMethod(@logParameter param: string) {
        console.log(`Method called with param: ${param}`);
    }
}

const obj = new MyClass();
obj.myMethod('test');

在上述代码中，logParameter 是一个参数装饰器。当 myMethod 被调用时，logParameter 会被执行，并输出目标类名、方法名以及参数的索引。

参数验证的实现

使用参数装饰器实现参数验证是非常常见的场景。比如，我们希望确保传入方法的参数是一个字符串且长度在一定范围内。

function validateStringLength(minLength: number, maxLength: number) {
    return function (target: any, propertyKey: string, parameterIndex: number) {
        return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
            const originalMethod = descriptor.value;
            descriptor.value = function (...args: any[]) {
                const param = args[parameterIndex];
                if (typeof param!=='string' || param.length < minLength || param.length > maxLength) {
                    throw new Error(`Invalid string length for parameter at index ${parameterIndex}`);
                }
                return originalMethod.apply(this, args);
            };
            return descriptor;
        };
    };
}

class StringValidatorClass {
    @validateStringLength(3, 10)
    validateString(str: string) {
        console.log(`Validating string: ${str}`);
    }
}

const validator = new StringValidatorClass();
try {
    validator.validateString('abc');
    validator.validateString('abcdefghijklmnop');
} catch (error) {
    console.error(error.message);
}

在这个例子中，validateStringLength 是一个高阶函数，它返回一个参数装饰器。这个装饰器通过修改方法的 descriptor.value 来实现参数验证。如果参数不符合长度要求，就会抛出错误。

日志记录参数

通过参数装饰器记录方法调用时传入的参数，可以方便地进行调试和问题排查。

function logParamValue(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            const paramValue = args[parameterIndex];
            console.log(`Method ${propertyKey} called with parameter at index ${parameterIndex}: ${paramValue}`);
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

class LoggerClass {
    @logParamValue
    logMessage(message: string) {
        console.log(`Logging message: ${message}`);
    }
}

const logger = new LoggerClass();
logger.logMessage('Hello, world!');

在上述代码中，logParamValue 装饰器记录了 logMessage 方法调用时传入的参数值。每次调用 logMessage 方法，都会在控制台输出参数的相关信息。

依赖注入

依赖注入是一种设计模式，通过参数装饰器可以在方法调用时注入所需的依赖。

interface Dependency {
    doSomething(): void;
}

class RealDependency implements Dependency {
    doSomething() {
        console.log('Dependency is doing something');
    }
}

function injectDependency(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            const dep: Dependency = new RealDependency();
            args[parameterIndex] = dep;
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

class ConsumerClass {
    @injectDependency
    consumeDependency(dep: Dependency) {
        dep.doSomething();
    }
}

const consumer = new ConsumerClass();
consumer.consumeDependency(null);

在这个示例中，injectDependency 装饰器为 consumeDependency 方法注入了 RealDependency 实例。即使在调用 consumeDependency 方法时传入了 null，实际上会被替换为真实的依赖实例并执行其方法。

参数装饰器与类装饰器、方法装饰器的协同工作

在实际项目中，参数装饰器很少单独使用，往往会与类装饰器或方法装饰器协同工作。例如，类装饰器可以用来配置一些全局的行为或设置，方法装饰器可以处理方法调用前后的通用逻辑，而参数装饰器专注于处理参数相关的功能。

// 类装饰器，用于设置一些全局配置
function globalConfig(target: any) {
    target.prototype.globalSetting = 'configured';
}

// 方法装饰器，记录方法调用时间
function logCallTime(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
        const start = new Date().getTime();
        const result = originalMethod.apply(this, args);
        const end = new Date().getTime();
        console.log(`Method ${propertyKey} called in ${end - start} ms`);
        return result;
    };
    return descriptor;
}

// 参数装饰器，验证数字参数是否为正数
function validatePositiveNumber(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            const param = args[parameterIndex];
            if (typeof param === 'number' && param <= 0) {
                throw new Error(`Parameter at index ${parameterIndex} must be a positive number`);
            }
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

@globalConfig
class MathOperations {
    @logCallTime
    addNumbers(@validatePositiveNumber num1: number, @validatePositiveNumber num2: number) {
        return num1 + num2;
    }
}

const mathOps = new MathOperations();
try {
    console.log(mathOps.addNumbers(2, 3));
    console.log(mathOps.addNumbers(-2, 3));
} catch (error) {
    console.error(error.message);
}

在上述代码中，globalConfig 类装饰器为 MathOperations 类添加了一个全局设置。logCallTime 方法装饰器记录了 addNumbers 方法的调用时间。validatePositiveNumber 参数装饰器确保传入 addNumbers 方法的数字参数为正数。通过这些装饰器的协同工作，我们可以实现更复杂和全面的功能。

参数装饰器在大型项目中的应用

在大型前端项目中，参数装饰器可以用于处理复杂的业务逻辑和通用功能。例如，在一个电商应用中，我们可能有许多涉及商品价格、数量等参数的方法。可以使用参数装饰器来确保这些参数的合法性。

// 验证商品价格必须为正数且在合理范围内
function validatePrice(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            const price = args[parameterIndex];
            if (typeof price === 'number' && (price <= 0 || price > 10000)) {
                throw new Error(`Invalid price at index ${parameterIndex}`);
            }
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

// 验证商品数量必须为正整数
function validateQuantity(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            const quantity = args[parameterIndex];
            if (typeof quantity === 'number' && (quantity <= 0 ||!Number.isInteger(quantity))) {
                throw new Error(`Invalid quantity at index ${parameterIndex}`);
            }
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

class ProductService {
    calculateTotalPrice(@validatePrice price: number, @validateQuantity quantity: number) {
        return price * quantity;
    }
}

const productService = new ProductService();
try {
    console.log(productService.calculateTotalPrice(100, 2));
    console.log(productService.calculateTotalPrice(-100, 2));
    console.log(productService.calculateTotalPrice(100, 2.5));
} catch (error) {
    console.error(error.message);
}

在这个电商应用的示例中，validatePrice 和 validateQuantity 参数装饰器分别对 calculateTotalPrice 方法的价格和数量参数进行验证。这有助于确保业务逻辑的正确性，减少潜在的错误。

参数装饰器与 AOP（面向切面编程）

参数装饰器是实现 AOP 的一种方式。AOP 允许我们将横切关注点（如日志记录、权限验证等）从业务逻辑中分离出来。通过参数装饰器，我们可以在不修改原有方法核心逻辑的情况下，为方法参数添加额外的功能。

// 权限验证参数装饰器
function checkPermission(target: any, propertyKey: string, parameterIndex: number) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;
        descriptor.value = function (...args: any[]) {
            // 假设这里有一个全局的权限验证函数
            if (!isUserAuthorized()) {
                throw new Error('User is not authorized to access this method');
            }
            return originalMethod.apply(this, args);
        };
        return descriptor;
    };
}

function isUserAuthorized() {
    // 实际的权限验证逻辑，这里简单返回 true 或 false
    return true;
}

class AdminService {
    @checkPermission
    performAdminAction(data: any) {
        console.log('Performing admin action with data:', data);
    }
}

const adminService = new AdminService();
try {
    adminService.performAdminAction({ key: 'value' });
} catch (error) {
    console.error(error.message);
}

在上述代码中，checkPermission 参数装饰器实现了权限验证的横切关注点。performAdminAction 方法无需关心权限验证的具体逻辑，只专注于自身的业务功能。

注意事项

装饰器执行顺序：当一个方法有多个参数装饰器时，它们的执行顺序是从最靠近参数的装饰器开始，向外依次执行。例如：

function decorator1(target: any, propertyKey: string, parameterIndex: number) {
    console.log('Decorator 1');
}

function decorator2(target: any, propertyKey: string, parameterIndex: number) {
    console.log('Decorator 2');
}

class SomeClass {
    someMethod(@decorator1 @decorator2 param: any) {
        // 方法体
    }
}

const someObj = new SomeClass();
someObj.someMethod('test');

在这个例子中，会先输出 Decorator 1，再输出 Decorator 2。

装饰器兼容性：虽然 TypeScript 支持装饰器，但不同的运行环境对装饰器的支持程度可能不同。在使用装饰器时，需要确保目标运行环境能够正确解析和执行装饰器相关的代码。通常，需要使用 Babel 等工具进行转译，以确保在不同环境下的兼容性。
性能影响：过多地使用装饰器可能会对性能产生一定的影响，因为装饰器会在运行时执行额外的代码。在设计和使用装饰器时，需要权衡功能和性能之间的关系，避免过度使用装饰器导致性能问题。

总结

TypeScript 参数装饰器为我们提供了一种强大的方式，能够在方法参数层面添加额外的功能。通过参数验证、日志记录、依赖注入等多种应用场景，我们可以提高代码的健壮性、可维护性和可测试性。在实际项目中，结合类装饰器和方法装饰器，参数装饰器能够更好地实现复杂的业务逻辑和 AOP 编程。然而，在使用参数装饰器时，我们也需要注意执行顺序、兼容性和性能等问题，以确保代码在各种环境下都能高效、稳定地运行。通过合理地运用参数装饰器，我们能够在前端开发中构建出更加灵活、可扩展的应用程序。