TypeScript装饰器：给代码“贴膜”的魔法

可视化演示

展示类/方法/属性/参数四种装饰器的应用、执行顺序与装饰器工厂模式，切换模式查看装饰器核心机制。

装饰器入门：认识手机美容店

小明的手机美容店开张了。第一位顾客拿来一部手机，要求“屏幕更耐磨、机身更好看”。小明没有拆开后盖改硬件，而是贴了一张钢化膜、套了一个渐变壳。手机还是那部手机，打电话、刷视频的体验却升级了。这个思路放到TypeScript里，就是装饰器：不修改类内部实现，在外部“贴一层”新能力。

装饰器是TypeScript提供的一种特殊声明语法，用@符号放在类、方法、属性或参数前面。它本质上是一个普通函数，只是被“注册”到了目标上。当类定义被求值时，装饰器函数会被自动调用一次。使用前需要在tsconfig.json中开启"experimentalDecorators": true，这也是很多初学者卡住的第一步。

装饰器的典型用途包括日志记录、权限校验、依赖注入、路由注册。比如NestJS里写@Controller('users')，这个@Controller就是一个装饰器，它不改变UserController内部的业务逻辑，只是在类定义时把路由前缀“贴”了上去。

小明给手机贴完膜，顾客满意地走了。装饰器的哲学正是如此——不追求“拆机改造”，而是用一层层“外包”来增强代码，这让代码的原始逻辑保持干净，也让增强能力可以被复用和组合。

类装饰器：整机包膜服务

今天店里来了一位“整机包膜”的顾客。他要的不是保护某个零件，而是给整个手机套上防摔壳。在TypeScript里，类装饰器就是这个“整机服务”——它作用在整个类上，像给类套了一层外壳。

类装饰器定义在类声明之前，接收唯一一个参数：类的构造函数。它接收的是“类的本体”，也就是那个可以被new的构造函数本身。你可以用它冻结类、扩展原型、添加静态属性，甚至返回一个全新的类来替换原来的类。

当装饰器返回一个新类时，这个新类会完全替换原类，新的对象实例都基于新类创建。通过class extends target的写法，可以给类追加字段或重写方法。这是实现“混入”（Mixin）功能的基础手段。

整机包膜让手机多了一层保护，顾客不必关心壳里是怎么走线的。类装饰器也一样：业务类不用管自己有没有被“包膜”，装饰器在类定义时静默完成一切。

function sealed(target: Function) {  Object.freeze(target);  Object.freeze(target.prototype);} @sealedclass User {}

方法装饰器：给摄像头贴镜片

手机美容店里常有一项服务：给摄像头贴蓝宝石镜片。顾客的手机主要功能是拍照，但镜头容易刮花。小明在镜头上加了保护，拍照功能不变，照片却不再模糊。方法装饰器对类里的方法做的正是这件事。

方法装饰器定义在方法声明之前，接收三个参数：第一个是类的原型对象（prototype），第二个是方法名（字符串），第三个是方法的属性描述符（PropertyDescriptor）。描述符里藏着value（函数本身）、writable、enumerable等控制选项，改写descriptor.value就能在方法调用前后插入逻辑。

这段代码展示了方法拦截的核心：先保存原始函数，再替换为一个“包装函数”，包装函数在调用前打印日志、调用后返回结果。apply(this, ...)保证this指向正确。这就是日志装饰器的底层原理，也是AOP（面向切面编程）在TypeScript中的实现方式。

给摄像头贴了镜片，拍照主体没变，照片却更清晰了。方法装饰器也是如此：原方法的逻辑完整保留，新的“镜片”在不打扰业务的前提下为方法增加了日志、校验或缓存能力。

function log(target: any, key: string, descriptor: PropertyDescriptor) {  const original = descriptor.value;  descriptor.value = function (...args: any[]) {    console.log('[日志] 调用', key, args);    return original.apply(this, args);  };}

属性装饰器：屏幕钢化膜

手机店里最受欢迎的单品是钢化膜。它贴在屏幕表面，不影响触控，却能在摔落时保护屏幕。属性装饰器就像钢化膜，贴在类的属性上，轻轻覆盖，不改变属性本身的读写逻辑。

属性装饰器定义在属性声明之前，接收两个参数：第一个是类的原型对象（静态属性则为构造函数），第二个是属性名。注意，它拿不到第三个descriptor参数，因此在默认的装饰器实现里，属性装饰器无法直接改写属性的value、writable等特性。它的返回值也会被忽略。

既然拿不到描述符，那属性装饰器有什么用？答案是“做标记”。它可以配合reflect-metadata把属性的附加信息（如字段长度、是否必填）记录下来，供框架后续读取。TypeORM的@Entity和@Column、class-validator的@IsEmail，本质都是先靠属性装饰器收集字段信息，再消费这些信息。

钢化膜贴在屏幕上，看不见摸不着改变，但摔手机时保护效果立竿见影。属性装饰器做标记时也是静悄悄的，等到框架需要读取这些标记时，它们才真正“显形”发力。

function format(target: any, key: string) {  console.log('属性装饰器：', key);}

参数装饰器：充电口防尘塞

手机美容店内还有一件不起眼的小配件——充电口防尘塞。它塞在手机的充电口里，不充电时防止灰尘进入，需要充电时拔掉即可。参数装饰器的作用对象，正是方法的“插孔”：参数位置。

参数装饰器定义在方法参数之前，接收三个参数：第一个是类的原型对象，第二个是方法名（如果是构造函数参数则忽略该参数值），第三个是参数在参数列表中的索引数字。第一个参数索引为0，第二个为1，依此类推。

参数装饰器无法获取参数的值，也无法修改参数内容。它只能在参数上“盖章”，记录这个位置有特殊语义。最常见的使用是配合reflect-metadata记录“参数的类型”或“参数是否必填”，再由方法装饰器读取这些元数据去执行真正的校验逻辑。NestJS的@Param('id')、@Body()就是参数装饰器的经典应用。

防尘塞不参与充电过程，却让充电口保持干净。参数装饰器不参与方法实际运算，却把“这位置有讲究”的信息留给框架，让依赖注入和数据校验变得自动化。

function required(target: any, key: string, index: number) {  console.log('第', index, '个参数被标记');}

装饰器工厂：定制套餐工坊

顾客多了，小明发现“统一贴膜”满足不了所有人：有人要磨砂膜，有人要防蓝光膜，有人要带图案的。于是店里推出“定制套餐”——顾客选好款式材质，工坊按配方生产对应的膜。装饰器工厂就是这套“定制工坊”。

装饰器工厂是一个返回装饰器函数的函数。它接收配置参数，在参数里定制装饰器的行为，然后返回真正被@使用的装饰器函数。调用工厂时需要在@后加括号传参，比如@log('用户模块')。

这在手写框架时特别有用：同样的“打日志”装饰器，通过工厂传入不同的前缀、级别、输出目标，就能复用在各个业务模块。NestJS里的@Controller('users')、@Get(':id')、@SetMetadata('role', 'admin')，全是装饰器工厂——先传路由或配置，再返回真正干活的装饰器。

定制套餐让每个顾客拿到自己心仪的膜。装饰器工厂让每个模块拥有专属配置的装饰器——同样的Log装饰器，给订单模块加“订单”前缀，给用户模块加“用户”前缀，代码复用率高且互不干扰。

function log(prefix: string) {  return function (target: any, key: string, descriptor: PropertyDescriptor) {    const fn = descriptor.value;    descriptor.value = function (...args: any[]) {      console.log(prefix + key, args);      return fn.apply(this, args);    };  };}

执行顺序：先贴内层再贴外层

一位顾客同时买了钢化膜、防摔壳和镜头贴。小明操作的顺序是：先贴镜头贴，再贴屏幕膜，最后套外壳。这个顺序很讲究——先做的“内层”，后做的“外层”，外层的壳包裹着内层的膜。装饰器的执行顺序同样是这个“洋葱模型”。

当多个装饰器同时挂在一个目标上时，规则有两条：第一，装饰器表达式（工厂调用）按从上到下的顺序求值；第二，求值得到的装饰器函数按从下到上的顺序调用。也就是说，@dec1 @dec2中dec2先执行，dec1后执行，dec1包裹在dec2外面。

不同类型装饰器应用在同一类上时，顺序也有约定：实例成员的参数装饰器先执行，然后是同成员的属性/方法装饰器（从右到左对每个成员处理），之后是构造器参数装饰器，最后才是类装饰器。属性/参数装饰器最“内层”，类装饰器最“外层”。

小明把最贴身的膜先贴好，再把壳套在外面，保护层层层叠加。装饰器的洋葱模型也一样：内层装饰器先感知原始行为，外层装饰器在它外围做进一步处理，顺序反了，效果就完全不同。

@dec1@dec2class User {} // dec2先执行，dec1后执行，最终效果 dec1(dec2(User))

reflect-metadata：手机档案标签

手机美容店生意好了，小明给每台手机贴一张小标签，写上“贴膜日期”“保修期”“客户偏好”。标签不改变手机功能，却让店里能快速查到每台手机的服务历史。reflect-metadata就是给代码对象贴“档案标签”的工具包。

reflect-metadata是一个npm库，为JavaScript/TypeScript提供了元数据读写能力。核心API包括Reflect.defineMetadata(key, value, target)写入、Reflect.getMetadata(key, target)读取、Reflect.hasMetadata判断。装饰器是“贴纸”，元数据是“贴纸上的字”——装饰器执行时通过defineMetadata把信息写到类或方法上，其他代码再通过getMetadata读出来。

这个库是NestJS、TypeORM等框架的基石。TypeORM的@Entity('user')会把表名写入元数据；NestJS的@Controller('users')把路由前缀写入元数据；依赖注入容器则通过元数据知道“这个构造参数要注入哪个服务”。装饰器负责收集信息，reflect-metadata负责存储和读取信息，二者配合完成元编程。

标签贴在手机上，手机自己不知道，但店员一查就知道该给这手机用什么保养方案。reflect-metadata把装饰器标记的信息变成可查询的数据，让框架能在运行时“读懂”代码结构，这就是NestJS能自动配路由、TypeORM能自动建表的原因。

import 'reflect-metadata'; Reflect.defineMetadata('role', 'admin', User);const role = Reflect.getMetadata('role', User); // 'admin'

AI 应用场景

Python 演示

import functoolsimport time  def log_execution(func):    """Print method call log like a TS method decorator."""    @functools.wraps(func)    def wrapper(*args, **kwargs):        print("[log] call {} args={} kwargs={}".format(func.__name__, args[1:], kwargs))        start = time.time()        result = func(*args, **kwargs)        cost = (time.time() - start) * 1000        print("[log] {} returned {} (cost {:.2f}ms)".format(func.__name__, result, cost))        return result    return wrapper  def validate_positive(func):    """Validate amount is positive like a TS param decorator."""    @functools.wraps(func)    def wrapper(self, amount):        if amount <= 0:            raise ValueError("amount must be positive")        return func(self, amount)    return wrapper  class BankAccount:    """A bank account class with decorators as phone stickers."""     def __init__(self, owner, balance=0):        self.owner = owner        self.balance = balance     @log_execution    def deposit(self, amount):        self.balance += amount        return self.balance     @log_execution    @validate_positive    def withdraw(self, amount):        if amount > self.balance:            raise ValueError("insufficient balance")        self.balance -= amount        return self.balance  def main():    account = BankAccount("xiaoming", 1000)    account.deposit(500)    account.withdraw(200)    print("final balance:", account.balance)  if __name__ == "__main__":    main()

1. def log_execution(func):装饰器本质是接收函数的函数，对应TS装饰器的“贴膜师”角色
2. def wrapper(*args, **kwargs):返回的包装函数，代替原方法执行，对应TS方法装饰器改写descriptor.value
3. result = func(*args, **kwargs)调用原始方法，保留原逻辑，像贴膜不影响手机功能
4. @log_executionPython语法糖，等价于deposit = log_execution(deposit)，和TS的@写法同源
5. if amount <= 0:参数校验逻辑，体现TS中“参数装饰器做标记、真正校验靠方法装饰器”的思想

常见误区

面试题