feat(@QueryProjection): support builder-based Q class generation

[Cole-SJ]

Multi-builder Support

• You can now define multiple @QueryProjection(useBuilder = true, builderName = "...") constructors per DTO.
• Each builder will be uniquely named inside the Q class and exposed via static factory methods.
• Advantages of { concise syntax, no explicit new, IDE friendly}

Highlights

1. Fully backward compatible — default remains constructor-style
2. No need to manually define a builder in the DTO
3. Improves readability and safety in complex DTO projections
4. All builder method arguments are Expression<?>, just like in constructor-style projections

Required builderName when useBuilder = true

To support multiple builder configurations, @QueryProjection(useBuilder = true) now requires a non-empty builderName.
This helps prevent name collisions when generating builder classes and factory methods.

Example

public class QueryProjectionBuilderTestEntity {
  private String property;
  private int intProperty;
  private Test test;

  @QueryProjection(useBuilder = true, builderName = "Test1")
  public QueryProjectionBuilderTestEntity(String property) {
    this.property = property;
  }

  @QueryProjection(useBuilder = true, builderName = "Test2")
  public QueryProjectionBuilderTestEntity(String property, int intProperty) {
    this.property = property;
    this.intProperty = intProperty;
  }

  @QueryProjection(useBuilder = true, builderName = "Test3")
  public QueryProjectionBuilderTestEntity(String property, int intProperty, Test test) {
    this.property = property;
    this.intProperty = intProperty;
    this.test = test;
  }

  public static class Test {
    private String property;
    private int intProperty;
  }

and generated QClass is below

/**
 * com.querydsl.apt.domain.QQueryProjectionBuilderTestEntity is a Querydsl Projection type for QueryProjectionBuilderTestEntity
 */
@SuppressWarnings("this-escape")
@Generated("com.querydsl.codegen.DefaultProjectionSerializer")
public class QQueryProjectionBuilderTestEntity extends ConstructorExpression<QueryProjectionBuilderTestEntity> {

    private static final long serialVersionUID = 264670126L;

    public QQueryProjectionBuilderTestEntity(com.querydsl.core.types.Expression<String> property) {
        super(QueryProjectionBuilderTestEntity.class, new Class<?>[]{String.class}, property);
    }

    public QQueryProjectionBuilderTestEntity(com.querydsl.core.types.Expression<String> property, com.querydsl.core.types.Expression<Integer> intProperty) {
        super(QueryProjectionBuilderTestEntity.class, new Class<?>[]{String.class, int.class}, property, intProperty);
    }

    public QQueryProjectionBuilderTestEntity(com.querydsl.core.types.Expression<String> property, com.querydsl.core.types.Expression<Integer> intProperty, com.querydsl.core.types.Expression<? extends QueryProjectionBuilderTestEntity.Test> test) {
        super(QueryProjectionBuilderTestEntity.class, new Class<?>[]{String.class, int.class, QueryProjectionBuilderTestEntity.Test.class}, property, intProperty, test);
    }

    public static class Test1Builder {

        private com.querydsl.core.types.Expression<String> property;

        public Test1Builder setProperty(com.querydsl.core.types.Expression<String> property) {
            this.property = property;
            return this;
        }

        public QQueryProjectionBuilderTestEntity build() {
            return new QQueryProjectionBuilderTestEntity(property);
        }

    }

    public static Test1Builder builderTest1() {
        return new Test1Builder();
    }

    public static class Test2Builder {

        private com.querydsl.core.types.Expression<String> property;

        private com.querydsl.core.types.Expression<Integer> intProperty;

        public Test2Builder setProperty(com.querydsl.core.types.Expression<String> property) {
            this.property = property;
            return this;
        }

        public Test2Builder setIntProperty(com.querydsl.core.types.Expression<Integer> intProperty) {
            this.intProperty = intProperty;
            return this;
        }

        public QQueryProjectionBuilderTestEntity build() {
            return new QQueryProjectionBuilderTestEntity(property, intProperty);
        }

    }

    public static Test2Builder builderTest2() {
        return new Test2Builder();
    }

    public static class Test3Builder {

        private com.querydsl.core.types.Expression<String> property;

        private com.querydsl.core.types.Expression<Integer> intProperty;

        private com.querydsl.core.types.Expression<? extends QueryProjectionBuilderTestEntity.Test> test;

        public Test3Builder setProperty(com.querydsl.core.types.Expression<String> property) {
            this.property = property;
            return this;
        }

        public Test3Builder setIntProperty(com.querydsl.core.types.Expression<Integer> intProperty) {
            this.intProperty = intProperty;
            return this;
        }

        public Test3Builder setTest(com.querydsl.core.types.Expression<? extends QueryProjectionBuilderTestEntity.Test> test) {
            this.test = test;
            return this;
        }

        public QQueryProjectionBuilderTestEntity build() {
            return new QQueryProjectionBuilderTestEntity(property, intProperty, test);
        }

    }

    public static Test3Builder builderTest3() {
        return new Test3Builder();
    }

}

Question

this commit

I don't want to update pom.xml of root, how can I resolve binary incompatible problem

[Cole-SJ]

@velo
Hello. I am truly honored to have created a PR to suggest adding a feature to this repository. I'd love to have my work reviewed by you, so please feel free to check out this PR at your convenience and give me any feedback you'd like to incorporate.
Thank you

[velo]

Question

this commit

I don't want to update pom.xml of root, how can I resolve binary incompatible problem

Hrmm

Codegen classes should be change prone, as they are internal classes used to generate code, no public apis. So I will take care of that.

Now, you change the annotation in a way that is backwards compatible. Looks like a big in the plugin

[Cole-SJ]

@velo
Thank you for your replying. Did you mean that you will fix those problems of the plugin in this PR?

[velo]

I think you can revert most of this now, probably all

[Cole-SJ]

thank you :)
I removed most of them except for @QueryProjection( because it would be exposed at public level interface 😢)