weixin_39830205
weixin_39830205
2021-01-11 20:22

The project should better demarcate what is API and what is not

Currently it is not crystal clear what is API and what is not.

Clearly top level classes such as GraphQL and ExecutionStrategy are API

But what about graphql.execution.Execution or graphql.execution.ValuesResolver. Are they API or implementation detail?

If we had to add new aspects to these classes and changed constructors etc are we breaking consumers?

I suggest that the API be made more clear.

Annotations are a great way to do this. The project could have 3 new annotations

(things you can call and wont change) (things you are meant to implement) (public things that are not API and may change)

This will allow the project to better keep semver sematics while evolving as necessary.

该提问来源于开源项目:graphql-java/graphql-java

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

6条回答

  • weixin_39557813 weixin_39557813 4月前

    regarding ` i think puttinginternal` in package name is a good practice

    点赞 评论 复制链接分享
  • weixin_39830205 weixin_39830205 4月前

    I agree on .internal in the package name as well as .api in the packages however that would be a major breaking change.

    Ideally it would be

     graphql.api.AnApiClass
    

    and

    graphql.internal.InternalImplementationClass
    

    the use of annotations are a way to not break current API while better documenting what is API

    点赞 评论 复制链接分享
  • weixin_39594191 weixin_39594191 4月前

    Because we are planning for a breaking change release I suggest that we use that to try to make it more clear what api vs internal is.

    But I think moving everything is not acceptable imho. Breaking stuff should be limited to what we think is really necessary. Annotating seems fine.

    点赞 评论 复制链接分享
  • weixin_39594191 weixin_39594191 4月前

    I like the idea to add two annotations and for example.

    点赞 评论 复制链接分享
  • weixin_39594191 weixin_39594191 4月前

    First shot: #411

    点赞 评论 复制链接分享
  • weixin_39594191 weixin_39594191 4月前

    we added annotations in #411 ...closing it therefore now: we will add the annotations as we go.

    点赞 评论 复制链接分享

相关推荐