In what format I should generate Kotlin types from schema to enable schema driven development.

[RIP21]

Hey folks. I'm kinda new to Kotlin and GraphQL Kotlin implementation, so I want your help to understand how should I generate stuff using https://graphql-code-generator.com/ so it will be as flexible as possible and will enable lazy calculation of some particular fields.
I know that you recommend consuming what kotlin-graphql schema generator generates, but we really want to get contract-driven development. E.g.
Flow like:

• Agree on schema between Frontend and Backend using GQL SDL
• Generate Base Kotlin Types (abstract classes?)
• Implement selection or all of those abstract classes in another package that is scanned by GQL Kotlin Schema Generator
• Get new GQL SDL generated by the kotlin schema generator
• Compare manually written schema with then one generated by kotlin schema generator using graphql-inspector on CI
• All good, merge it.

What currently https://graphql-code-generator.com/ and its kotlin preset generates with withTypes flag is all types in the schema (only union and interfaces are missing, tho solvable) as data classes.
I'm wondering, what format will be the best in your opinion? Keep them data classes? Or make them abstract private fields and with getters and setters as abstract methods generated to enable heavy lazy fields implementations (when you do not just have a simple getter as a resolver, but a fun with some implementation that is lazily called by GraphQL Engine only when it's queried).

So, what approach will you take if you were me? :) Or maybe there are heavy cons against this approach and you can stop me before I do a mistake? :)

Kotlin gives a lot of syntax sugar, so I need a bit of guidance here. As I'm unsure if kotlin-graphql calls object.field or always object.getField() under the hood so that's why all those questions about abstract classes :)

And just to reiterate in other words:
Idea is

schema {
  query: Query
}

type Query {
  me: User!
}

type User {
  name: String!
  organization: Organization!
}

type Organization {
  id: ID!
}

Will generate GqlGeneratedBase.kt although unsure how to generate it properly so it fits my request :)

abstract class BaseQuery(
  val me: BaseUser
)

abstract class BaseUser(
  val name: String
  val organization: Organization
)

abstract class BaseOrganization(
  val id: java.util.UUID
)

[RIP21]

Ok something like that maybe?
Generated

interface BaseUser {
    val name: String
    val organization: BaseOrganization
}

interface BaseQuery {
    val me: BaseUser
}

interface BaseOrganization {
    val id: UUID
}

Implementation:

data class Organization(
    override val id: UUID
): BaseOrganization

data class User (
    override val name: String,
): BaseUser {
    override val organization: Organization
        get() {
            TODO("Lazy call to database for organization")
        }
}

class RootQuery: Query, BaseQuery {
    override val me: BaseUser
        get() = TODO("Not yet implemented")
}

Whadayathink?

[dariuszkuc]

Hello 👋
Based on your described flow I am unsure how much value you will get from auto generated stubs, i.e. if you are going to re-implement the generated stubs anyway what is the point in generating them in the first place?

Using code generator to create a new project from an SDL could be useful - i.e. it would allow you to generate some skeleton app that you then fill with logic could save some setup time, but I am unsure how that flow would look like in an already established app. If your code generator generates the data classes you would still need to create some resolver to be able to retrieve those (well at least for the top level query) and you would also be somewhat limited in your code as you wouldn't be able to lazily evaluate those fields. I guess it could work if it generates some abstract interfaces (marked as @GraphQLIgnore) so then you could decide on the implementation logic there. Your generation logic should also be fairly smart to also generate functions for any fields that take arguments.

If all you are trying to do is verify that original SDL matches the one implemented by graphql-kotlin why not just skip the code generation part and simply compare the generated SDL artifact? (your second to last step) IMHO adding code generation there just unnecessarily complicates things.

[RIP21]

I totally agree that it feels like overkill, but my fellow backend folks (I'm mostly Frontend but JVM past and experience with GraphQL with TS kinda forces me to step up and make their GraphQL stuff better) want to have a contract-driven development, not afterward the implementation, but kinda while developing, integrated into whole flow :)
So idea is that, when you change manually created schema (contract), it changes base interfaces that in return break your implementations until you fix them. So it kinda helps guide implementation to have it 1:1 with a manually written one. And, yeah, all Base interfaces will be ignored from generation.

Anyway, I'll experiment with that and will let you know :) But, I agree, just comparing manually written, to autogenerated at the end seems to be OK and the simplest solution :)

[smyrick]

I will add to this that I think you should either take one of two approaches. Doing your proposed third combined approach will be overhead that is not needed.

SDL-First Development

Also known as Schema-First. I think SDL-First better describes the architecture as regardless of what development you have. GraphQL should always be about the schema between clients and server. This wouldn't require the use of our libraries at all and you could just use raw graphql-java to write and SDL file, and the manually write the resolver functions that match the SDL exactly. This would allow your client and server team to share the same SDL file and have a written contract outside of the codebase.

Code-First Development

We created graphql-kotlin because we found the process of writing SDL and resolvers functions separate to be verbose and unneeded. We also view the SDL as a build artifact and something that is generated, shared, and validated with tooling. Even in Expedia Group we do schema first design. We have schema reviews with designers, front-end, and back-end teams and come up with our schema using the SDL as it is an easy non-code way to mock out what everyone wants. Then it is on clients to write code to consume that, and API teams to write code to produce that schema. However after the initially schema design there is not much SDL work we need to do. Everything else is automated tooling and running checks, or adding one new field in the schema so we don't need to modify a shared document for the API team to make changes.

There are pros and cons to both solutions, but obviously we are a bit biased 😉

The more traditional SDL-first approach works well for other languages to though, like JS, Python, and Ruby that do not have type systems

[RIP21]

Sure, thanks, I'm aware of that as I came from Typescript background that has perfect resolvers signatures generator from the SDL by graphql-codegen mentioned above. So I thought something similar is possible with Kotlin, to have mixed approach. I guess it maybe still kinda possible, but will require a lot of thinking and fighting with Kotlin type system and Kotlin Generator logic too. But it will not worth it engineering effort :)

@smyrick can I ask you, how you folks structure your app so there are no GraphQL Ignores all over the place, so mixed concerns, and so only few packages are scanned by generator and no unused types or minimal amount of unused types are end up in generated SDL.
So imagine a monolith app and you have some models, repositories, services that do some business logic on models and whatnot and then an API layer that collects it all together and gives it back to client.

So far, the only way I see to have it under control is to remap original models, to some sort of "Dtos" even tho it feels redundant, it's the only way I guess.

[smyrick]

We do not expose any underlying objects to the GraphQL layer. Instead we have specific schema classes that we can add graphql descriptions and logic. This means that the GraphQL layer is separate from any DBs or APIs that power the schema. This abstraction layer also allows us to refactor any part of the schema later on without having to inform clients. So we could move just one field to come from a different source or an entire response at the top level but clients do not care if there existing queries still work

[RIP21]

@smyrick makes sense. Exactly what I thought is the right thing to do, but just wanted to be sure I have a correct understanding of the possible mess it can cause if I'll mix business stuff with API stuff and that it's better to part them as quick as possible :)

[RIP21]

The answer would be, just set up a schema printer and compare manually created extension of the schema e.g. a contract agreed with FE or any other consumer or engineer, the one that is generated by the Kotlin GraphQL using graphql-inspector diff command :) As generating resolvers interfaces, or smth similar to that mostly makes no sense :) Tho I did it, but it's not as flexible or elegant enough to be a working thing. With raw graphql-java DataFetchers can work tho but it's way too verbose for my taste :)

The whole thing will look like this:

So printer bean:

package your.package

import com.expediagroup.graphql.extensions.print
import graphql.schema.GraphQLSchema
import org.springframework.stereotype.Component
import java.io.File


@Component
class GraphQLSchemaPrinter(val schema: GraphQLSchema) {
    init {
        printToFile()
    }
    final fun printToFile() {
        File("./generated.schema.graphql").writeText(schema.print())
    }
}

Here is the gradle task in kotlin syntax if anyone wondering :)

tasks {
    register<NpmTask>("graphqlDiff") {
        dependsOn("npmInstall")
        description =
            "Logically (not like a string, but AST wise) compares generated schema by KotlinGraphQLSchemaGenerator with manually written schema.graphql file"
        if (!file("./generated.schema.graphql").exists()) {
            throw GradleException(
                "You should have generated.schema.graphql file generated. Run the app, or tests, to generate it."
            )
        }
        inputs.files(fileTree("./") {
            include("*.graphql")
        })
        setArgs(listOf("run", "gql:diff"))
    }
}

implying that you have gradle-node-plugin installed and package.json that looks like that,

{
  "name": "backend",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "gql:diff": "graphql-inspector diff \"schema.graphql\" \"generated.schema.graphql\""
  },
  "devDependencies": {
    "@graphql-inspector/cli": "2.3.0",
    "graphql": "15.4.0",
    "yargs": "16.2.0"
  }
}

You can also run this command on CI after test run, as after test run, if you're using Spring, this printer will print the generated.schema.graphql file as Context for your tests will probably create this printer bean so the file too :)
Just to be sure you haven't forgotten to run this command locally before committing. Or, well, the pre-commit hook is also a great place for this command to be executed.

[RIP21]

@dariuszkuc I assume answer to this question, but just to be 100% sure. Any way to get schema string without running the whole app?
The only thing that comes to my mind is to get some super lightweight context configuration with only needed to generation beans, and run it from some gradle command, but I guess it's rather fragile and hard :)

[smyrick]

@RIP21 If you are using spring to autowire in schema modifiers and configuration, then running the app one way to get the schema. If there was some other way you could organize your code without spring, you can have a Gradle task to just run the schema-generator but it would still require you to know where the configuration classes are and load those in.

Edit. See comment below

[RIP21]

@smyrick any hints how to start it and kill immediately after it's done using scripts? :)
My first thought is to run and ping every second some heartbeat endpoint until 200 to stop. Or, well, just ping file system till the schema file is flushed to the file system :)
Maybe something more elegant? :)

[smyrick]

@RIP21 Sorry, I actually misspoke. I looked at our internal code and we have a custom Maven plugin that reads the class path and manually builds a GraphQLConfigurationProperties, scans the classpath for all the Query, Mutation, and Subscription implementations and then calls the toSchema function.

So this happens outside of spring but we do have custom code to load our specific SchemaGeneratorHooks which is why it is not in open source today. We may be able to find a way around this and create an open-source Maven Plugin version but for Gradle you would have to do the same thing.

[RIP21]

Will be glad to hack around to get gradle version of that. With a Maven
example it should be straightforward i guess.