Description
According to the HTTP specification, the HTTP response status can be any 3-digit integer.
In Spring Framework, the HTTP status codes are enumerated in HttpStatus. Because this type is a Java enum, we need to have workarounds to allow for status codes not in the enum. For instance, the ClientHttpResponse interfaces offers both getStatusCode as well as getRawStatusCode, as does WebClient's ClientResponse, and we have similar workarounds in other places.
We cannot change HttpStatus from a enum to a class like we did for HttpMethod in #27697, because HttpStatus is used in the ResponseStatus annotation, where class instances can not be used as values.
@philwebb suggested that we can introduce a new interface HttpStatusCode, which is implemented by HttpStatus. Code that currently returns a HttpStatus will return this new HttpStatusCode instead, and we will deprecate the methods that return the raw status codes. All methods that accepts the raw integer values will still be available, we will only deprecate the integer returning methods.
Instances of the HttpStatusCode are obtained via static valueOf(int) factory method, which returns a HttpStatus enum entry if one is available for the given integer, and a default implementation otherwise. This way, we can assure that HttpStatus instance comparisons (i.e. if (statusCode == HttpStatus.OK)) will keep working as they currently do.