Protocol-Oriented Programming and Cocoa (Part 2)

[[403619]]

This article is a summary of the author's keynote speech at the iOS session at MDCC 16 (Mobile Developer Conference). Published on November 29, 2016 and last updated on October 22, 2020

You can find the Keynote used in the talk here [1], and some sample code can be found in the official repo of MDCC 2016 [2].

The first part [3] mainly introduces some theoretical content, including the problems existing in object-oriented programming, the basic concepts and decision-making models of protocol-oriented programming, etc. This article (Part 2) mainly shows some sample codes that the author uses in daily life to combine protocol-oriented thinking with Cocoa development, and explains them.

1. Use the protocol in daily development

WWDC 2015 had an excellent keynote speech on POP: #408 Protocol-Oriented Programming in Swift[4]. Apple engineers used two examples, drawing charts and sorting, to explain the idea of ​​POP. We can use POP to decouple and make code more reusable through combination. However, the content involved in #408 is more theoretical, and our daily app development is more about dealing with the Cocoa framework. After watching #408, we have been thinking about how to apply the idea of ​​POP to daily development?

In this section, we will take a practical example to see how POP can help us write better code.

1.1 Protocol-based network requests

The network request layer is an ideal place to practice POP. In the following example, we will start from scratch and use the simplest protocol-oriented approach to build a less perfect network request and model layer. It may contain some unreasonable designs and couplings, but it is the easiest initial result.

Then we will gradually sort out the various parts and refactor them in a way that separates responsibilities. Finally, we will test this network request layer. Through this example, I hope to design POP code with many excellent features including type safety, decoupling, easy testing, and good scalability.

• Talk is cheap, show me the code.

1.1.1 Preliminary Implementation

First, what we want to do is request a JSON from an API and convert it into an instance usable in Swift.

 { "name" : "onevcat" , "message" : "Welcome to MDCC 16!" }

We can create a new project and add User.swift as a model:

 // User .swift
 import Foundation 
 
 struct User {
 let name : String
 let message: String 
     
 init?(data: Data) {
        guard let obj = try? JSONSerialization.jsonObject( with : data, options: []) as ? [String: Any ] else {
 return nil
 }
        guard let name = obj?[ "name" ] as ? String else {
 return nil
 }
        guard let message = obj?[ "message" ] as ? String else {
 return nil
 } 
         
 self.name = name  
        self.message = message
 }
 }

User.init(data:) parses the input data (obtained from the network request API) into a JSON object, extracts the name and message from it, and constructs a User instance representing the API return. It's very simple.

Now let's look at the interesting part, which is how to use POP to request data from a URL and generate the corresponding User. First, we can create a protocol to represent the request. For a request, we need to know its request path, HTTP method, required parameters and other information. At the beginning, the protocol may be like this:

 enum HTTPMethod: String {
 case GET
 case POST
 } 
 
 protocol Request {
 var host: String { get }
 var path: String { get } 
     
    var method: HTTPMethod { get }
    var parameter: [String: Any ] { get }
 }

By concatenating host and path, we can get the API address we need to request. For simplicity, HTTPMethod now only includes two request methods: GET and POST. In our example, we will only use GET request.

Now, you can create a new UserRequest to implement the Request protocol:

 struct UserRequest: Request {
 let name : String 
     
    let host = "https://api.onevcat.com"  
 var path: String {
 return   "/users/\(name)"  
 }
    let method: HTTPMethod = .GET
    let parameter: [String: Any ] = [:]
 }

UserRequest has a name attribute with no initial value defined, and the other attributes are defined to meet the protocol. Because the request parameter username name will be passed through the URL, it is sufficient for parameter to be an empty dictionary. With the protocol definition and a specific request that meets the definition, we now need to send the request. In order for any request to be sent in the same way, we define the sending method on the Request protocol extension:

 extension Request {
    func send(handler: @escaping ( User ?) -> Void) {
 // ... implementation of send
 }
 }

In the send(handler:) parameter, we define the escapeable (User?) -> Void. After the request is completed, we call this handler method to notify the caller whether the request is completed. If everything is normal, a User instance is returned, otherwise nil is returned.

We want this send method to be universal for all Requests, so obviously the callback parameter type cannot be User. By adding an associated type to the Request protocol, we can abstract the callback parameter. Add the following at the end of Request:

 protocol Request {
 ...
 associatedtype Response
 }

Then in UserRequest, we also add the type definition accordingly to satisfy the protocol:

 struct UserRequest: Request {
 ...
 typealias Response = User  
 }

Now, let's reimplement the send method. Now, we can use Response instead of the specific User to make send more general. Here we use URLSession to send the request:

 extension Request {
    func send(handler: @escaping (Response?) -> Void) {
        let url = URL(string: host.appending(path))!
        var request = URLRequest(url: url)
        request.httpMethod = method.rawValue 
         
 // In this example we don't need `httpBody`, in practice we may need to convert parameter to data
        // request.httpBody = ... 
         
        let task = URLSession.shared.dataTask( with : request) {
            data, res, error in  
 // Processing results
 print(data)
 }
 task.resume()
 }
 }

By concatenating the host and path, we can get the entry point of the API. Create a request based on this URL, configure it, generate a data task and send the request. The remaining work is to convert the data in the callback into the appropriate object type and call the handler to notify the external caller. For User, we know that we can use User.init(data:), but for the general Response, we don’t know how to convert the data into a model. We can define a parse(data:) method in Request to require the specific type that satisfies the protocol to provide a suitable implementation. In this way, the task of providing the conversion method is "decentralized" to UserRequest:

 protocol Request {
 ...
 associatedtype Response
    func parse(data: Data) -> Response?
 } 
 
 struct UserRequest: Request {
 ...
 typealias Response = User  
    func parse(data: Data) -> User ? {
 return   User (data: data)
 }
 }

With the method of converting data into Response, we can process the result of the request:

 extension Request {
    func send(handler: @escaping (Response?) -> Void) {
        let url = URL(string: host.appending(path))!
        var request = URLRequest(url: url)
        request.httpMethod = method.rawValue 
         
 // In this example we don't need `httpBody`, in practice we may need to convert parameter to data
        // request.httpBody = ... 
         
        let task = URLSession.shared.dataTask( with : request) {
 data, _, error in  
            if let data = data, let res = parse(data: data) {
                DispatchQueue.main.async { handler(res) }
 } else {
                DispatchQueue.main.async { handler(nil) }
 }
 }
 task.resume()
 }
 }

Now, let's try to request this API:

 let request = UserRequest( name : "onevcat" )
 request.send { user   in  
 if let user = user {
        print( "\(user.message) from \(user.name)" )
 }
 } 
 
 // Welcome to MDCC 16! from onevcat

1.1.2 Refactoring, separation of concerns

Although the requirements can be met, the above implementation can be said to be very bad. Let's take a look at the definition and extension of Request now:

 protocol Request {
 var host: String { get }
 var path: String { get } 
     
    var method: HTTPMethod { get }
    var parameter: [String: Any ] { get } 
     
 associatedtype Response
    func parse(data: Data) -> Response?
 } 
 
 extension Request {
    func send(handler: @escaping (Response?) -> Void) {
 ...
 }
 }

The biggest problem here is that Request manages too many things. A Request should only define the request entry and the expected response type, but now Request not only defines the value of the host, but also knows how to parse the data. Finally, the send method is tied to the implementation of URLSession and exists as part of Request.

This is unreasonable because it means we cannot update the way to send requests without changing the request, they are coupled together. Such a structure makes testing extremely difficult. We may need to intercept the request through stub and mock, and then return the constructed data, which will use the content of NSURLProtocol, or introduce some third-party testing frameworks, which greatly increases the complexity of the project. This may be an option in the Objective-C era, but in the new era of Swift, we have much better ways to deal with this matter.

Let's start refactoring the previous code and add tests for them. First, we separate send(handler:) from Request. We need a separate type to be responsible for sending requests. Based on the POP development method, we start by defining a protocol that can send requests:

 protocol Client {
    func send(_ r: Request, handler: @escaping (Request.Response?) -> Void)
 } 
 
 // Compilation error

The above declaration is quite clear from a semantic point of view, but because Request is a protocol with associated types, it cannot be used as an independent type. We can only use it as a type constraint to restrict the input parameter request. The correct declaration should be:

 protocol Client {
    func send<T: Request>(_ r: T, handler: @escaping (T.Response?) -> Void) 
 
 var host: String { get }
 }

In addition to using the generic <T: Request> approach, we also moved the host from Request to Client, where it is more appropriate. Now, we can remove the Request protocol extension that contains send and create a new type to satisfy Client. As before, it will use URLSession to send the request:

 struct URLSessionClient: Client {
    let host = "https://api.onevcat.com"   
     
    func send<T: Request>(_ r: T, handler: @escaping (T.Response?) -> Void) {
        let url = URL(string: host.appending(r.path))!
        var request = URLRequest(url: url)
        request.httpMethod = r.method.rawValue 
         
        let task = URLSession.shared.dataTask( with : request) {
 data, _, error in  
            if let data = data, let res = r.parse(data: data) {
                DispatchQueue.main.async { handler(res) }
 } else {
                DispatchQueue.main.async { handler(nil) }
 }
 }
 task.resume()
 }
 }

Now the part of sending the request is separated from the request itself, and we define the Client using a protocol. In addition to URLSessionClient, we can use any type that satisfies this protocol and sends the request. This way, the specific implementation of the network layer is no longer related to the request itself, and we will further see the benefits of doing so when testing later.

There is still a problem in this implementation, that is the parse method of Request. The request should not and does not need to know how to parse the data, this work should be handed over to Response. And now we have not made any restrictions on Response. Next we will add a new protocol, and the type that meets this protocol will know how to convert a data into the actual type:

 protocol Decodable {
 static func parse(data: Data) -> Self?
 }

Decodable defines a static parse method. Now we need to add this restriction to the Response associated type of Request. This way, we can ensure that all Responses can parse the data. The parse declaration in the original Request can also be removed:

 // Final Request protocol
 protocol Request {
 var path: String { get }
    var method: HTTPMethod { get }
    var parameter: [String: Any ] { get } 
     
    // associated type Response
    // func parse(data: Data) -> Response?
    associatedtypeResponse: Decodable
 }

The last thing to do is to make User satisfy Decodable and modify the parsing code of URLSessionClient above to use the parse method in Response:

 extension User : Decodable {
 static func parse(data: Data) -> User ? {
 return   User (data: data)
 }
 } 
 
 struct URLSessionClient: Client {
    func send<T: Request>(_ r: T, handler: @escaping (T.Response?) -> Void) {
 ...
     // if let data = data, let res = parse(data: data) {
        if let data = data, let res = T.Response.parse(data: data) {
 ...
 }
 }
 }

Finally, we clean up the host and parse that are no longer needed in UserRequest, and a type-safe, decoupled, protocol-oriented network layer appears before us. When we want to call UserRequest, we can write:

 URLSessionClient().send(UserRequest( name : "onevcat" )) { user   in  
 if let user = user {
        print( "\(user.message) from \(user.name)" )
 }
 }

Of course, you can also add a singleton to URLSessionClient to reduce the creation overhead of the request, or add a Promise call method to the request, etc. Under the organization of POP, these changes are very natural and will not involve other parts of the request. You can add other API requests to the network layer in a similar way to the UserRequest type. You only need to define the necessary content of the request without worrying about touching the specific implementation of the network.

1.1.3 Network layer test

Declaring the Client as a protocol brings us the additional benefit that we are not limited to using a specific technology (such as URLSession here) to implement network requests. With POP, you just define a protocol for sending requests, and you can easily use mature third-party frameworks such as AFNetworking or Alamofire to build specific data and handle the underlying implementation of the request. We can even provide a set of "fake" responses to requests for testing. This is conceptually close to the traditional stub & mock approach, but the implementation is much simpler and clearer. Let's take a look at how to do it.

We first prepare a text file and add it to the test target of the project as the content returned by the network request:

 // File name: users:onevcat
 { "name" : "Wei Wang" , "message" : "hello" }

Next, you can create a new type that satisfies the Client protocol. However, unlike URLSessionClient, the send method of this new type does not actually create a request and send it to the server. What we need to verify during testing is that if the server responds correctly according to the document after a request is sent, then we should also be able to get the correct model instance. So what this new Client needs to do is to load the defined result from the local file and then verify whether the model instance is correct:

 struct LocalFileClient: Client {
    func send<T : Request>(_ r: T, handler: @escaping (T.Response?) -> Void) {
 switch r.path {
 case   "/users/onevcat" :
            guard let fileURL = Bundle( for : ProtocolNetworkTests.self).url(forResource: "users:onevcat" , withExtension: "" ) else {
 fatalError()
 }
            guard let data = try? Data(contentsOf: fileURL) else {
 fatalError()
 }
            handler(T.Response.parse(data: data))
 default :
            fatalError( "Unknown path" )
 }
 } 
     
 // In order to meet the requirements of `Client`, we will not actually send a request
 let host = ""  
 }

What LocalFileClient does is very simple. It first checks the path attribute of the input request. If it is /users/onevcat (which is the request we need to test), it reads the predefined file from the test bundle, parses it as the return result, and then calls the handler. If we need to add tests for other requests, we can add new case items. In addition, the part of loading local file resources should use a more general writing method, but since we are just an example here, we will not dwell on it too much.

With the help of LocalFileClient, it is now easy to test UserRequest:

 func testUserRequest() {
    let client = LocalFileClient()
    client.send(UserRequest( name : "onevcat" )) {
 user   in  
        XCTAssertNotNil( user )
        XCTAssertEqual( user !. name , "Wei Wang" )
 }
 }

In this way, we can perform request testing without relying on any third-party testing libraries, nor using complex technologies such as URL proxy or runtime message forwarding. Keeping the code and logic simple is crucial for project maintenance and development.

1.1.4 Scalability

Because of the high degree of decoupling, this POP-based implementation provides a relatively loose possibility for code expansion. As we have just said, you do not have to implement a complete Client yourself, but can rely on the existing network request framework to implement the request sending method.

In other words, you can easily replace a request method in use with another one without affecting the definition and use of the request. Similarly, in the processing of Response, we now define Decodable and parse the model in our own handwritten way. We can also use any third-party JSON parsing library to help us quickly build model types. This only requires implementing a method to convert Data to the corresponding model type.

If you are interested in POP-based network requests and model parsing, you may want to take a look at the APIKit[5] framework. The method we show in the example is the core idea of ​​this framework.

Using protocols to help improve code design

Through protocol-oriented programming, we can be freed from traditional inheritance and assemble programs in a more flexible way, like building blocks. Each protocol focuses on its own function, and thanks to protocol extension, we can reduce the risk of shared state brought by classes and inheritance, making the code clearer.

A high degree of protocolization helps with decoupling, testing, and expansion. Using protocols in combination with generics can free us from the troubles of dynamic calls and type conversions, ensuring the security of the code.

Question session

After the keynote speech, several friends raised some very meaningful questions, which I have summarized here. There may be slight differences between the questions and answers and the situation at that time, so they are for reference only.

When I was watching the demo just now, I found that you always write the protocol first, instead of the struct or class. Should we define the protocol first when practicing POP?

• I wrote the protocol directly because I already had a full understanding of what I was going to do and I hoped that the speech would not exceed the time limit. However, in actual development, you may not be able to write a suitable protocol definition at the beginning. It is recommended that you define it "roughly" as I did in the demo, and then get a final version through continuous refactoring. Of course, you can also sketch an outline with pen and paper first, and then define and implement the protocol. Of course, no one stipulates that you must define the protocol first. You can also start with ordinary types, and then when you find common points or encounter the difficulties we mentioned earlier, look back and see if protocol-oriented is more appropriate. This requires certain POP experience.

Since POP has so many advantages, do we no longer need object-oriented programming and can we switch to protocol-oriented programming?

• The answer may disappoint you. In our daily projects, Cocoa, which we deal with every day, is actually a framework with a strong OOP color. In other words, it may be impossible for us to abandon OOP for a period of time. However, POP can actually "coexist harmoniously" with OOP, and we have seen many examples of using POP to improve code design. In addition, it should be added that POP is not a silver bullet, and it has a bad side. The biggest problem is that protocols increase the level of abstraction of the code (this is the same as class inheritance), especially when your protocol inherits other protocols, this problem is particularly serious. After several layers of inheritance, it becomes difficult to meet the end protocol, and it is difficult for you to determine which protocol a certain method meets. This will make the code quickly complicated. If a protocol does not describe many common points, or can be quickly understood, it may be simpler to use basic types.

Thank you for your speech. I would like to ask about your use of POP in your projects.

• We use a lot of POP concepts in our project. The network request examples in the demo above are extracted from actual projects. We think such requests are very easy to write because the code is very simple and it is very comfortable for newcomers to take over. In addition to the model layer, we also use some POP codes in the view and view controller layers, such as NibCreatable for creating views from nibs, NextPageLoadable for supporting paging requests for tableview controllers, EmptyPage for displaying pages when the list is empty, and so on. Due to time constraints, it is impossible to explain them one by one, so here I only picked a representative and not very complex network example. In fact, each protocol makes our code, especially the View Controller, shorter and makes testing possible. It can be said that our project has benefited a lot from POP, and we should continue to use it.

This article is reprinted from the WeChat public account "Swift Community", which can be followed through the following QR code. To reprint this article, please contact the Swift Community public account.