diff --git a/zh/annotation.md b/zh/annotation.md index ab0b99871..c4a1408b0 100644 --- a/zh/annotation.md +++ b/zh/annotation.md @@ -27,14 +27,99 @@ Hyperf 使用了 [doctrine/annotations](https://github.com/doctrine/annotations) ## 使用注解 +注解一共有3种应用对象,分别是 `类`、`类方法` 和 `类属性`。 + ### 使用类注解 +类注解定义是在 `class` 关键词上方的注释块内,比如常用的 `@Controller` 和 `@AutoController` 就是类注解的使用典范,下面的代码示例则为一个正确使用类注解的示例,表明 `@ClassAnnotation` 注解应用于 `Foo` 类。 +```php +/** + * @ClassAnnotation() + */ +class Foo {} +``` + ### 使用类方法注解 -### 使用属性注解 +类方法注解定义是在方法上方的注释块内,比如常用的 `@RequestMapping` 就是类方法注解的使用典范,下面的代码示例则为一个正确使用类方法注解的示例,表明 `@MethodAnnotation` 注解应用于 `Foo::bar()` 方法。 +```php +class Foo +{ + /** + * @MethodAnnotation() + */ + public function bar() + { + // some code + } +} +``` + +### 使用类属性注解 + +类属性注解定义是在属性上方的注释块内,比如常用的 `@Value` 和 `@Inject` 就是类属性注解的使用典范,下面的代码示例则为一个正确使用类属性注解的示例,表明 `@MethodAnnotation` 注解应用于 `Foo::bar()` 方法。 +```php +class Foo +{ + /** + * @PropertyAnnotation() + */ + private $bar; +} +``` + +### 注解参数传递 + +- 传递主要的单个参数 `@DemoAnnotation("value")` +- 传递字符串参数 `@DemoAnnotation(key1="value1", key2="value2")` +- 传递数组参数 `@DemoAnnotation(key={"value1", "value2"})` ## 自定义注解 ### 定义一个自定义注解 -#### 自定义注解收集器 \ No newline at end of file +#### 创建一个注解类 + +在任意地方创建注解类,如下代码示例: + +```php +namespace App\Annotations; + +use Hyperf\Di\Annotation\AbstractAnnotation; + +/** + * @Annotation + * @Target({"METHOD","PROPERTY"}) + */ +class Bar extends AbstractAnnotation +{ + // some code +} + +/** + * @Annotation + * @Target("CLASS") + */ +class Foo extends AbstractAnnotation +{ + // some code +} +``` + +> 注意注解类的 `@Annotation` 和 `@Target` 注解为全局注解,无需 `use` + +其中 `@Target` 有如下参数: +- `METHOD` 注解允许定义在类方法上 +- `PROPERTY` 注解允许定义在类属性上 +- `CLASS` 注解允许定义在类上 +- `ALL` 注解允许定义在任何地方 + +我们注意一下在上面的示例代码中,注解类都继承了 `Hyperf\Di\Annotation\AbstractAnnotation` 抽象类,对于注解类来说,这个不是必须的,但对于 Hyperf 的注解类来说,继承 `Hyperf\Di\Annotation\AnnotationInterface` 接口类是必须的,那么抽象类在这里的作用是提供极简的定义方式,该抽象类已经为您实现了`注解参数自动分配到类属性`、`根据注解使用位置自动按照规则收集到 AnnotationCollector` 这样非常便捷的功能。 + +#### 自定义注解收集器 + +注解的收集时具体的执行流程也是在注解类内实现的,相关的方法由 `Hyperf\Di\Annotation\AnnotationInterface` 约束着,该接口类要求了下面 3 个方法的实现,您可以根据自己的需求实现对应的逻辑: + +- `public function collectClass(string $className): void;` 当注解定义在类时被扫描时会触发该方法 +- `public function collectMethod(string $className, ?string $target): void;` 当注解定义在类方法时被扫描时会触发该方法 +- `public function collectProperty(string $className, ?string $target): void` 当注解定义在类属性时被扫描时会触发该方法 \ No newline at end of file