Azure / Azure/azure-functions-java-library

Change design to a Method-level annotation model

Offen
#51 6 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:java-functions
Vorherrschende Sprache
Java
Sterne
45
Forks
49
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

Currently, triggers and bindings are defined at the parameter-level. Given the amount of config parameters that the annotations may require, or that the user may want to set, this approach often makes the code extremely hard to read.

Only one trigger is allowed on a (Java method) function, making Trigger a definitive candidate to be a Method annotation, instead of a method-parameter annotation.

Example of Cosmos DB trigger:

```java
@FunctionName("cosmosDBMonitor")
public void cosmosDbProcessor(
@CosmosDBTrigger(name = "items",
databaseName = "ToDoList",
collectionName = "Items",
leaseCollectionName = "leases",
reateLeaseCollectionIfNotExists = true,
connectionStringSetting = "AzureCosmosDBConnection") String[] items,
final ExecutionContext context ) {
context.getLogger().info(items.length + "item(s) is/are changed.");
}
```

In the example above, it is hard to quickly find where the actual method body starts.

A better approach would be to move the annotation to the method-level:

```java
@FunctionName("cosmosDBMonitor")
@CosmosDBTrigger(name = "items", databaseName = "ToDoList",
collectionName = "Items", leaseCollectionName = "leases",
createLeaseCollectionIfNotExists = true,
connectionStringSetting = "AzureCosmosDBConnection",
parameter = "items")
public void cosmosDbProcessor(String[] items, final ExecutionContext context ) {
context.getLogger().info(items.length + "item(s) is/are changed.");
}
```

Moving the annotation to the method level, requires a new way to bind the trigger and the input object. This can be done in two ways:

1. Add a new annotation parameter called `parameter` where the user defines the name of the method parameter that will take the input
2. Add a new method-parameter annotation type to link the trigger with the input object.

The code snippet above covers option 1.

For option 2, an example would be:

```java
@FunctionName("cosmosDBMonitor")
@CosmosDBTrigger(name = "items", databaseName = "ToDoList",
collectionName = "Items", leaseCollectionName = "leases",
createLeaseCollectionIfNotExists = true,
connectionStringSetting = "AzureCosmosDBConnection")
public void cosmosDbProcessor(@TriggerObject String[] items, final ExecutionContext context ) {
context.getLogger().info(items.length + "item(s) is/are changed.");
}
```

In the above example for option 2, a new annotation called `@TriggerObject` is defined to bind the trigger with the method-parameter.

This structure provides two benefits:

1. Prevents developers from attempting to add two triggers to the same method, and only finding out if this works or note after they try to run on Azure Functions (whether local or on Azure).
2. Makes the function method body easier to read.

The same approach should be considered for other types: Bindings, and Outputs.

Request for feedback: @JonathanGiles, @pragnagopa, @asavaritayal, @eduardolaureano, @jeffhollan

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

Beginnen Sie mit dem Vergleich des vorgeschlagenen methodenbezogenen Trigger-Modells mit dem aktuellen parameterbezogenen Modell, das im Issue beschrieben ist. Klären Sie, ob das Parameter-Binding einen benannten Parameter oder eine neue @TriggerObject-Annotation verwenden sollte, und prüfen Sie anschließend dieselbe Entscheidung für Bindings und Ausgaben. Als abgeschlossen gilt die Aufgabe, wenn das Annotation-Design mehrere Trigger pro Methode verhindert und Funktionssignaturen leichter lesbar macht.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
java
Bereich
developer-experience
Issue-Typ
Refactoring
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.