Java注解（1）：码农的小秘

很多码农在写代码的时候不太爱写注释，结果任务一多，时间一长，需求一改，就完全不知道当初自己都干了些啥了。好在现在大多数编程语言都有注释功能，能够在代码里面做一些备注，不至于时间长了忘掉。但这些注释只是给人看的，机器并不会处理这些信息，而是把这些注释当作垃圾一样无视。

反过来，如果有些编程语言因为升级更新，替换掉了某些功能特性而导致开发受阻甚至不能使用，该怎么办呢？——这也难不倒科学家。他们想：既然码农可以写注释提醒自己不忘记代码是干什么的，那是不是也可以通过某种方法来提醒他们代码会出问题呢？

还真被他们找到了，这就是注解！

比如，像刚才说的场景：如果某个Java类被废弃了，怎么让码农们知道呢？——使用@Deprecated注解的就可以办到，就像这样：

如果类的方法被废弃，也是一样：

注解是JDK1.5中新增加的特性，它的作用说白了就是Java语言层面的「注释」，它主要是用来向JVM（Java虚拟机）解释说明类、对象、方法、属性、接口、抽象类等元素的信息。它是对数据的描述，可以说是关于数据的数据。

Java中提供了一些预定义的注解，例如@Override、@SuppressWarnings、@FunctionalInterface等，而Java开发框架的顶流Spring又在在此之上，提供了更多的注解，例如@Autowired、@Service、@RestController。

因为有了这些注解，码农的开发效率大大提高。举个最常见的栗子来说：

没有使用@Autowired注解：

/**
 * 用户接口控制器
 *
 * @author 湘王
 */
public class UserController {
    private UserService userService;

    // 用户登录接口
    public void login(User user) {
        // 先实例化UserService的实现类UserServiceImpl
        userService = new UserServiceImpl();
        // 继续实例化UserServiceImpl类中需要用到的各种其他类和对象
        // TODO
    }

    // 用户登出接口
    public void logout(String userid) {
        // 同样的过程可能要再来一次
        userService = new UserServiceImpl();
        // 继续实例化UserServiceImpl类中需要用到的各种其他类和对象
        // TODO
    }
}

使用了@Autowired注解：

/**
 * 用户接口控制器
 *
 * @author 湘王
 */
public class UserController {
    @Autowired
    private UserService userService;

    // 用户登录接口
    public void login(User user) {
        // 直接调用UserServiceImpl实现类的各种对象和方法
        // TODO
    }

    // 用户登出接口
    public void logout(String userid) {
        // 直接调用UserServiceImpl实现类的各种对象和方法，而且不用重复实例化
        // TODO
    }
}

用了注解之后可以说是「舒服得不能再舒服了」。

Java目前提供了五种标准的注解（元注解，就是可以用来创造其他注解的注解）

@Target：表示注解可以用于哪些地方

@Retention：表示注解的适用范围

@Documented：将注解保存在javadoc中

@Inherited：允许子类继承父类的注解

@Repeatable：允许一个注解可被使用一次或多次

/**
 * 定义注解可以应用在哪里
 * PACKAGE：包
 * TYPE：类、接口（包括注解类型）或者enum
 * CONSTRUCTOR：构造器
 * METHOD：方法
 * FIELD：字段（包括enum实例）
 * LOCAL_VARIABLE：局部变量
 * PARAMETER：参数
 *
 * 如果省去@Target注解，那么注解可以应用于所有的ElementType
 *
 * @author xiangwang
 */
@Target(ElementType.METHOD)
/**
 * 定义了注解在哪里可用
 * SOURCE：源代码，将被编译器丢弃
 * CLASS：class文件，会被JVM丢弃
 * RUNTIME：运行时，一直保留
 */
@Retention(RetentionPolicy.RUNTIME)
// 将此注解保存在Javadoc中
@Documented
// 允许子类继承父类的注解
@Inherited
// 允许一个注解可以被使用一次或者多次
// @Repeatable(value = Object.class)
// 标记注解，不包含任何元素
public @interface Test {}

尝试着举一个小栗子，比如最常见的，验证密码有效性：

/**
 * 定义注解
 *
 * @author xiangwang
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface UseCase {
   int id() default -1;
   String description() default "";
}

可以用两种方式来看看效果：

1、直接运行注解：

/**
 * 使用注解
 *
 * @author xiangwang
 */
public class PasswordUtils {
   // 使用@UserCase注解
   @UseCase(id = 1, description = "密码必须至少包含一位数字")
   public static boolean validate(String password) {
      return (password.matches("\\w*\\d\\w*"));
   }

   public static void main(String[] args) {
      System.out.println(PasswordUtils.validate("w1errd"));
   }
}

2、或者使用昨天介绍的反射来解析注解：

/**
 * 解析注解
 *
 * @author xiangwang
 */
public class UseCaseTracker {
   public static void trackUseCases(List<Integer> useCases, Class<?> cl) {
      for (Method m : cl.getDeclaredMethods()) {
         UseCase uc = m.getAnnotation(UseCase.class);
         if (uc != null) {
            System.out.println("发现注解id：" + uc.id() + " - 注解description：" + uc.description());
            // 剔除已有注解
            useCases.remove(Integer.valueOf(uc.id()));
         }
      }
      useCases.forEach(i -> System.out.println("缺少用例id：" + i));
   }

   public static void main(String[] args) {
      List<Integer> useCases = IntStream.range(1, 5).boxed().collect(Collectors.toList());
      trackUseCases(useCases, PasswordUtils.class);
   }
}

这是最最简单的注解形式。注解真正的用武之地是各类开发框架，尤其是ORM框架，明天就自己尝试着实现一个：）