查看“Trtr:注解编程”的源代码

{{标题
| Trtr注解编程
}}
{{副标题
| 使用注解在运行时自动处理字段和方法的控制反转框架
}}
'''注解编程'''，是指在[[Trtr:Trtr/zh]]的代码中，使用注解替代手动编写过多重复代码的设计模式，本质上是由一个[[IoC]]框架代替完成。

= 约束 =
任何需要被自动处理的字段和方法必须被"static"关键字修饰<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/filed/FieldAccess.java |title=FieldAccess.java at main · cao-awa/the-road-to-reality |publisher=草二号机 |date=2023-03-16 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/728911a683ee57ce94dc59212318e37073604bed/src/main/java/com/github/cao/awa/trtr/framework/accessor/filed/FieldAccess.java |archivedate=2023-03-16 |accessdate=2023-03-16 }}</ref>，这也包括已经自行初始化的字段。

= 示例 =
在任意位置（合理的软件包下）编写如下代码，而后直接运行Minecraft，此时不需要自行去注册这个方块，[[Trtr:方块反射框架]]会处理好这一切。

以下字段"IDENTIFIER"和"SETTINGS"必须存在，必须大写。

<syntaxhighlight lang="java">
@Auto
public class TestBlock extends TrtrBlock {
    @Auto
    public static final Identifier IDENTIFIER = Identifier.of("trtr", "test");
    @Auto
    public static final Settings SETTINGS = FabricBlockSettings.of(Material.STONE, MapColor.GRAY);

    @Auto
    public TestBlock(Settings settings) {
        super(settings);
    }
}
</syntaxhighlight>

任何被支持的字段都可以以类似以上的方式被自动处理，而开发者只需要写更少量的重复代码。

== 自动初始化 ==
Trtr的[[IoC]]框架支持自动初始化字段，例如此处有一方块物品：
<syntaxhighlight lang="java">
@Auto
public class TestBlockItem extends TrtrBlockItem {
    @Auto
    public static final FabricItemSettings SETTINGS = new FabricItemSettings();

    @Auto
    public AluniteOreItem(Block block, Settings settings) {
        super(block, settings);
    }
}
</syntaxhighlight>

这时候可以直接在TestBlock中加入字段"ITEM"或"BLOCK_ITEM"，而不需要任何的赋值。如下所示：
<syntaxhighlight lang="java">
@Auto
public class TestBlock extends TrtrBlock {
    @Auto
    public static final Identifier IDENTIFIER = Identifier.of("trtr", "test");
    @Auto
    public static final Settings SETTINGS = FabricBlockSettings.of(Material.STONE, MapColor.GRAY);
    @Auto
    public static TestBlockItem ITEM;
//  另一种方式声明方块物品
//  @Auto
//  public static Class<TestBlockItem> ITEM = TestBlockItem.class;

    @Auto
    public TestBlock(Settings settings) {
        super(settings);
    }
}
</syntaxhighlight>

= 约定 =
在使用注解编程时，只有匹配约定字段的名称和类型才会被自动处理。

== 字段 ==
=== 标识符 ===
标识符（Identifier）约定名称为"IDENTIFIER"、类型为：[[Minecraft:net.minecraft.util.Identifier]]<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/identifier/IdentifierAccessor.java |title=IdentifierAccessor.java at main · cao-awa/the-road-to-reality |publisher=草awa |date=2023-03-15 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/0c273d23aa961cdc5d031ca6d52fed12ed68867f/src/main/java/com/github/cao/awa/trtr/framework/accessor/identifier/IdentifierAccessor.java |archivedate=2023-03-15 |accessdate=2023-03-16 }}</ref>。

=== 设置（方块） ===
方块设置（Settings）约定名称为"SETTINGS"、备选"SETTING"，类型为：[[Minecraft:net.minecraft.block.AbstractBlock.Settings]]的子类<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/block/setting/BlockSettingAccessor.java |title=BlockSettingAccessor.java at main · cao-awa/the-road-to-reality |publisher=草awa |date=2023-03-16 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/0c273d23aa961cdc5d031ca6d52fed12ed68867f/src/main/java/com/github/cao/awa/trtr/framework/accessor/block/setting/BlockSettingAccessor.java |archivedate=2023-03-16 |accessdate=2023-03-16 }}</ref>，如[[Minecraft:net.fabricmc.fabric.api.object.builder.v1.block.FabricBlockSetting|net.fabricmc.fabric.api.object.builder.v1.block.FabricBlockSetting]]。<ref name="example_block">{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/block/example/ExampleBlock.java |title=ExampleBlock.java at main · cao-awa/the-road-to-reality |publisher=草二号机 |date=2023-03-15 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/40ff64d245df47ca0c8b25db78252ab0cccbc62f/src/main/java/com/github/cao/awa/trtr/block/example/ExampleBlock.java |archivedate=2023-03-15 |accessdate=2023-03-16 }}</ref>

=== 方块物品 ===
方块物品（BlockItem）约定名称为"ITEM"、备选"BLOCK_ITEM"，类型为：[[Minecraft:net.minecraft.item.BlockItem|net.minecraft.item.BlockItem]]或其子类<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/block/item/BlockItemAccessor.java |title=BlockItemAccessor.java at main · cao-awa/the-road-to-reality |publisher=草awa |date=2023-03-16 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/0c273d23aa961cdc5d031ca6d52fed12ed68867f/src/main/java/com/github/cao/awa/trtr/framework/accessor/block/item/BlockItemAccessor.java |archivedate=2023-03-16 |accessdate=2023-03-16 }}</ref>。

或者以形如Class<? extends BlockItem>的方式声明类型。<ref name="example_block"></ref>

=== 方块战利品（数据生成） ===
方块战利品（Loot）约定名称为"LOOT"、备选"LOOT_PROVIDER"，类型为[[Minecraft:net.fabricmc.fabric.api.datagen.v1.provider.SimpleFabricLootTableProvider]]的子类或[[Trtr:com.github.cao.awa.trtr.framework.data.gen.loot.LootFactory]]的实现<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/data/gen/loot/LootDataGeneratorAccessor.java |title=LootDataGeneratorAccessor.java at main · cao-awa/the-road-to-reality |publisher=草awa |date=2023-03-16 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/4cffec2d6a283a8d4421dcd2d93faff805d2817b/src/main/java/com/github/cao/awa/trtr/framework/accessor/data/gen/loot/LootDataGeneratorAccessor.java |archivedate=2023-03-16 |accessdate=2023-03-16 }}</ref>，如[[Trtr:com.github.cao.awa.trtr.data.gen.loot.GenericBlockLootProvider]]。

或者以形如Class<? extends SimpleFabricLootTableProvider>或LootFactory<? extends SimpleFabricLootTableProvider>的方式声明类型。<ref name="example_block"></ref>

=== 方块模型（数据生成） ===
方块模型（models）约定名称为"MODEL"、备选"MODEL_PROVIDER"，类型为[[Minecraft:net.fabricmc.fabric.api.datagen.v1.provider.FabricModelProvider]]的子类<ref>{{cite web |url=https://github.com/cao-awa/the-road-to-reality/blob/main/src/main/java/com/github/cao/awa/trtr/framework/accessor/data/gen/model/ModelDataGeneratorAccessor.java |title=ModelDataGeneratorAccessor.java at main · cao-awa/the-road-to-reality |publisher=草awa |date=2023-03-15 |archiveurl=https://github.com/cao-awa/the-road-to-reality/blob/4cffec2d6a283a8d4421dcd2d93faff805d2817b/src/main/java/com/github/cao/awa/trtr/framework/accessor/data/gen/model/ModelDataGeneratorAccessor.java |archivedate=2023-03-15 |accessdate=2023-03-16 }}</ref>，如[[Trtr:com.github.cao.awa.trtr.data.gen.model.GenericBlockModelProvider]]。

或者以形如Class<? extends BlockItem>的方式声明类型。<ref name="example_block"></ref>

== 方法 ==

== 注解 ==
=== 自动处理 ===
要让框架自动处理一个类，需要在类上添加[[Trtr:com.github.cao.awa.apricot.annotations.Auto|@Auto]]注解，照标准样式，其他任何需要字段处理的字段和方法也应加上此注解。

=== 要求工具挖掘 ===
在目标类上添加如下注解以让框架自动处理挖掘时需要的工具种类和级别：

斧：@AxeMining(MiningLevels.DIAMOND)

锄：@HoeMining(MiningLevels.DIAMOND)

镐：@PickaxeMining(MiningLevels.DIAMOND)

剪刀：@ShearsMining(MiningLevels.DIAMOND)

铲：@ShovelMining(MiningLevels.DIAMOND)

剑：@SwordMining(MiningLevels.DIAMOND)

=== 数据生成 ===
数据生成并未要求添加任何注解，使用@DataGen注解标记一个字段或类是用于数据生成的，用于降低代码阅读难度。

= 样式 =
在代码中，@Auto注解虽然被标准要求在每一个会被自动处理的字段、方法和类上出现，以统一标准样式。但这一要求不是强制性的，只需要至少在类上添加注解即可使用注解编程。

而标准样式是在向主仓库创建拉取请求或用任意其他方式提交代码时所必须的，非规范样式的代码会被拒绝合并。

= 参考 =
{{reflist}}