C++ API 设计指南

5星 · 超过95%的资源需积分: 10 5 浏览量更新于2024-07-24 收藏 6.38MB PDF 举报

"API Design for C++ 是一本关于如何在C++编程语言中设计高效、易用和可维护的应用程序接口(API)的专业书籍。作者Martin Reddy提供了深入的指导，帮助开发者理解API设计的关键原则和最佳实践。" API设计是软件开发中的一个重要环节，尤其是在C++这样的强类型语言中，良好的API设计能够极大地提高代码的重用性、可扩展性和可维护性。以下是一些基于C++ API设计的关键知识点： 1. **命名约定**：API设计的第一步是选择合适的命名约定，这有助于确保代码的一致性和可读性。C++中常见的命名约定包括驼峰式命名（camelCase）和下划线分隔命名（snake_case）。此外，还需要考虑命名空间（namespace）来避免命名冲突。 2. **接口封装**：C++的类（class）提供了一种强大的方式来封装数据和操作。设计时应明确接口的公共方法（public methods），隐藏实现细节（private或protected members），以实现数据的封装和信息隐藏。 3. **异常安全**：API设计应考虑异常处理，确保在抛出异常时不会破坏对象状态。这可能涉及使用异常安全的构造函数、析构函数以及在异常发生时能正确恢复的函数。 4. **模板（Template）**：C++的模板允许创建泛型代码，适应不同类型的参数。明智地使用模板可以创建高度可重用的API，但也要注意避免过度使用导致的编译器膨胀问题。 5. **错误处理**：API应清晰地定义错误处理策略，这可能是通过返回值、异常、错误码或者组合使用。一个好的做法是提供易于理解的错误信息，并允许用户优雅地处理失败情况。 6. **版本控制**：API的更新可能会对依赖它的代码产生影响。因此，设计时应考虑版本控制，如使用命名空间来区分不同版本的API，或者提供兼容性层。 7. **设计模式**：理解并应用设计模式，如工厂模式、观察者模式、单例模式等，可以帮助创建更灵活和可扩展的API。 8. **文档**：良好的API文档是必不可少的，它应该清晰地解释每个函数的作用、参数、返回值以及可能抛出的异常。Doxygen等工具可以帮助自动生成文档。 9. **测试驱动开发（TDD）**：在设计API时采用TDD的方法，先编写测试用例，然后编写满足这些测试的API，可以确保API的质量和功能完整性。 10. **一致性**：保持API设计的一致性是至关重要的。一致性使得用户更容易理解和使用API，减少学习曲线。通过遵循这些原则和最佳实践，开发者可以在C++中创建出强大、易于理解和使用的API，从而提升软件的整体质量和用户体验。《API Design for C++》这本书将深入探讨这些概念，为读者提供宝贵的指导。

As an example of a well-known API, Microsoft’s Windows API (often referred to as the Win32

API) is a collection of C functions, data types, and constants that enable programmers to write appli-

cations that run on the Windows platform. This include s functions for file handling, process and

thread management, creating graphical user interfaces, talking to networks, and so on.

The Win32 API is an example of plain C API rather than a C

API. While you can use a C API

directly from a C

program, a good example of a specific C

API is the Standard Template Library

(STL). The STL contains a set of container classes , iterators for navigating over the elements in

those containers, and various algorithms that act on those containers (Josuttis, 1999). For instance,

the collection of algorithms includes high-level operations such as

std::search(), std::reverse(),

std::sort(), and std::set_intersection(). The STL therefore presents a logical interface to

the task of manipulating collections of elements, without exposing any of the internal details for

how each algorithm is implemented.

TIP

An API is a logical interface to a software component that hides the internal details required to implement it.

1.2 WHAT’S DIFFERENT ABOUT API DESIGN?

Interfaces are the most import ant code that a developer writes. That’s because problems in an inter-

face are far mor e costly to fix than problems in the associated implementation code. As a result, the

process of developing shared APIs demands more attention than standard application or Graphical

User Interface (GUI) development. Of course, both should involve best design practices; however,

in the case of API development, these are absolutely critical to its success. Specifically, some of

the key differentiating factors of API development include the following.

• An API is an interface designed for developers, in much the same way that a GUI is an inter-

face designed for end users. In fact, it’s been sai d that an API is a user interface for program-

mers (Arnold, 2005). As such, your API could be used by thousands of developers around the

world, and it will undoubtedly be used in ways that you never intended (Tulach, 2008). You

must anticipate this in your design. A well-designed API can be your organization’s biggest

asset. Conversely, a poor API can create a support nightmare and even turn your users toward

your competitors (Bloch, 2005), just as a buggy or difficult-to-use GUI may force an end user

to switch to a different application.

• Multiple applications can share the same API. Figure 1.1 showed that a single application can

be composed of multipl e APIs. However, any one of those APIs could also be reused in sev-

eral other applications. This means that while problems in the code for any given application

will only affect that one application, errors in an API can affect all of the applications that

depend on that functionality.

• You must strive for backward compatibilit y whenever you change an API. If you make an

incompatible change to your interface, your clients’ code may fail to compile, or worse their

code could compile but behave differently or crash intermittently. Imagine the confusion and

chaos that would arise if the signature of the

printf() function in the standard C library was

4 CHAPTER 1 Introduction

different for different compilers or platforms. The simple “Hello World” program may not

look so simple any more:

#include <stdio.h>

#ifdef _WIN32

#include <windows.h>

#endif

#ifdef __cplusplus

#include <iostream>

#endif

int main(int, char *argv[])

{

#if __STRICT_ANSI__

printf("Hello World\n");

#elif defined(_WIN32)

PrintWithFormat("Hello World\n");

#elif defined(__PRINTF_DEPRECATED__)

fprintf(stdout, "Hello World\n");

#elif defined(__PRINTF_VECTOR__)

const char *lines[2] ¼ {"Hello World", NULL};

printf(lines);

#elif defined(__cplusplus)

std::cout << "Hello World" << std::endl;

#else

#error No terminal output API found

#endif

return 0;

}

This may seem like a contrived example, but it’s actually not that extreme. Take a look at the stan-

dard header files that come with your compiler and you will find declarations that are just as convo-

luted and inscrutable, or perhaps worse.

• Due to the backward compatibility requirement, it is critical to have a change control process

in place. During the normal development process, many developers may fix bugs or add new

features to an API. Some of these developers may be junior engineers who do not fully under-

stand all of the aspects of good API design. As a result, it is important to hold an API review

before releasing a new version of the API. This involves one or more senior engineers check-

ing that all changes to the interface are acceptable, have been made for a valid reason, and are

implemented in the best way to maintain backward compatibility. Many open source APIs

also enforce a change request process to gain approval for a change before it is added to

the source code.

• APIs tend to live for a long time. There can be a large upfront cost to produce a good API

because of the extra overhead of planning, design , versioning, and review that is necessary.

However, if done well, the long-term cost can be substantially mitigated because you have

the ability to make radical changes and improvements to your software without disrupting

your clients. That is, your development velocity can be greater due to the increased flexibility

that the API affords you.

51.2 What’s different about API design?

• The need for good documentation is paramount when writing an API, particularly if you do

not provide the source code for your implementation. Users can look at your header files to

glean how to use it, but this does not define the behavior of the API, such as acceptable input

values or error conditions. Well-written, consistent, and extensive documentation is therefore

an imperative for any good API .

• The need for automated testing is similarly very high. Of course, you should always test your

code, but when you’re writing an API you may have hundreds of other developers, and

thousands of their users, depending on the correctness of your code. If you are making major

changes to the implementation of your API, you can be more confident that you will not break

your clients’ programs if you have a thorough suite of regression tests to verify that the

desired API behavior has not changed.

Writing good APIs is difficult. While the necessary skills are founded on general software design

principles, they also require additional knowledge and development processes to address the points

just listed. Howeve r, the principles and techniques of API design are rarely taught to engineers. Nor-

mally, these skills are only gained through experience—by making mistakes and learning empirically

what does and does not work (Henning, 2009). This book is an attempt to redress this situation, to

distill the strategies of industrial-strength, future-proof API design that have been evolved through

years of software engineering experie nce into a comprehensive, practical, and accessible format.

TIP

An API describes software used by other engineers to build their applications. As such, it must be well-designed,

documented, regression tested, and stable between releases.

1.3 WHY SHOULD YOU USE APIs?

The question of why you should care about APIs in your own software projects can be interpreted in

two different ways: (1) why should you design and write your own APIs or (2) why should you use

APIs from other providers in your applications? Both of these perspectives are tackled in the follow-

ing sections as I present the various benefits of using APIs in your projects.

1.3.1 More Robust Code

If you are writing a module to be used by other developers, either for fellow engineers within your

organization or for external customers of your library, then it would be a wise investment to create

an API for them to access your functionality. Doing so will offer you the following benefits.

• Hides implementation. By hiding the implementation details of your module, you gain the

flexibility to change the implementation at a future date without causing upheaval for your

users. Without doing so, you will either (i) restrict yourself in terms of the updates you can

make to your code or (ii) force your users to rewrite their code in order to adopt new versions

of your library. If you make it too onerous for your clients to update to new versions of your

software, then it is highly likely that they will either not upgra de at all or look elsewhere for

an API that will not be as much work for them to maintain. Good API design can therefore

significantly affect the success of your business or project.

6 CHAPTER 1 Introduction

• Increases longevity. Over time, systems that expose their implementation details tend to

devolve into spaghetti code where every part of the system depends on the internal details

of other parts of the system. As a result, the system becomes fragile, rigid, immobile, and vis-

cous (Martin, 2000). This often results in organizations having to spend significant effort to

evolve the code toward a better design or simply rewrite it from scratch. By investing in good

API design up front and paying the incremental cost to maintain a coherent design, your soft-

ware can survive for longer and cost less to maintain in the long run. I’ll delve much deeper

into this point at the start of Chapter 4.

• Promotes modularization. An API is normally devised to address a specific task or use case.

As such, APIs tend to define a modular grouping of functionality with a coherent focus.

Developing an application on top of a collection of APIs promotes loosely coupled and mod-

ular architectures where the behavior of one module is not dependent on the internal details of

another module.

• Reduces code duplication. Code duplication is one of the cardinal sins of software engineer-

ing and shoul d be stamped out whenever possible. By keeping all of your code’s logic behind

a strict interface that all clients must use, you centralize the behavior in a single place. Doing

so means that you have to update only one place to change the behavior of your API for all of

your clients. This can help remove duplication of implementation code throughout your code

base. In fact, many APIs are created after discovering duplicated code and deciding to consol-

idate it behind a single interface. This is a good thing.

• Removes hardcoded assumptions. Many programs may contain hardcoded values that are

copied throughout the code, for example, using the filename

myprogram.log whenever data

are written to a log file. Instead, APIs can be used to provide access to this information with-

out replicating these constant values across the code base. For example, a

GetLogFilename()

API call could be used to replace the hardcoded "myprogram.log" string.

• Easier to change the implementation. If you have hidden all of the implementation details

of your module behind its public interface then you can change those implementation details

without affecting any code that depends on the API. For example, you might decide to change

a file parsing routine to use

std::string containers instead of allocating, freeing, and reallo-

cating your own

char * buffers.

• Easier to optimize. Similarly, with your implementation details hidden successfully, you can

optimize the performance of your API without requiring any change s to your clients’ code.

For example, you could add a caching solution to a method that performs some computation-

ally intensive calculation. This is possible because all attempts to read and write your under-

lying data are performed via your API, so it becomes much easier to know when you must

invalidate your cached result and recompute the new value.

1.3.2 Code Reuse

Code reuse is the use of existing software to build new software. It is one of the holy grails of mod-

ern software development. APIs provide a mechanism to enable code reuse.

In the early years of software development, it was common for a company to have to write all of

the code for any application they produced. If the program needed to read GIF images or parse a text

file, the company would have to write all that code in-house. Nowadays, with the proliferation of

71.3 Why should you use APIs?

good commercial and open source libraries, it makes much more sense to simply reuse code that

others have written. For example, there are various open source image reading APIs and XML pars-

ing APIs that you can download and use in your application today. These libraries have been refined

and debugged by many developers around the world and have been battle-tested in many other

programs.

In essence, software development has become much more modular, with the use of distinct com-

ponents that form the building blocks of an application and talk together via their published APIs.

The benefit of this approach is that you don’t need to understand every detail of every software com-

ponent, in the same way that for the earlier house building analogy you can delegate many details to

professional contractors. This can translate into faster development cycles, either because you can

reuse existing code or decouple the schedule for various components. It also allows you to concen-

trate on your core business logic instead of having to spend time reinventing the wheel.

One of the difficulties in achieving code reuse, however, is that you often have to come up with

a more general interface than you originally intended. That’s because other clients may have addi-

tional expectations or requirements. Effective code reuse therefore follows from a deep understand-

ing of the clients of your software and designing a system that integrates their collective interests

with your own.

APIs AND THE WEB

The trend toward applications that depend on third-party APIs is particularly popular in the field of cloud

computing. Here, Web applications rely more and more on Web services (APIs) to provide core functionality. In the

case of Web mashups, the application itself is sometimes simply a repackaging of multiple existing services to

provide a new service, such as combining the Google Maps API with a local crimes statistics database to provide a

map-based interface to the crime data.

In fact, it’s worth taking a few moments to highlight the importance of C

API design in Web development.

A superficial analysis might conclude that server-side Web development is confined to scripting languages, such

as PHP, Perl, or Python (the “P” in the popular LAMP acronym), or .NET languages based on Microsoft’s ASP

(Active Server Pages) technology. This may be true for small-scale Web development. However, it is noteworthy

that many large-scale Web services use a C

backend to deliver optimal performance.

In fact, Facebook developed a product called HipHop to convert their PHP code into C

to improve the

performance of their social networking site. C

API design therefore does have a role to play in scalable Web

service development. Additionally, if you develop your core APIs in C

, not only can they form a high-performance

Web service, but your code can also be reused to deliver your product in other forms, such as desktop or mobile

phone versions.

As an aside, one potential explanation for this shift in software development strategy is the result

of the forces of globalization (Friedman, 2008; Wolf, 2004). In effect, the convergence of the Inter-

net, standard network protocols, and Web technologies has created a leveling of the software playing

field. This has enabled companies and individuals all over the world to crea te, contribute, and com-

pete with large complex software projects. This form of globalization promotes an environment

where companies and developers anywhere in the world can forge a livelihood out of developing

software subsystems. Other organizations in different parts of the world can then build end-user

applications by assembling and augmenting these building blocks to solve specific problems. In

terms of our focus here, APIs provide the mechanism to enable this globalization and componentiza-

tion of modern software development.

8 CHAPTER 1 Introduction

剩余445页未读，继续阅读

dctfjy

粉丝: 16
资源: 71

C++ API 设计指南

API Design for C++ 无水印pdf

api design for c++ pdf

API Design for C++的示例代码

C++接口设计经典：马丁·雷迪的API Design for C++

MK.API.Design.for.C++

C++ API 设计指南

Oasys是一个使用Maven进行项目管理的OA办公自动化系统。该项目基于Spring B

peewee-3.15.0-cp310-cp310-win_amd64.whl

Delphi 12控件之FR安装工具24.7z

基于树莓派使用sht20采集温湿度信息，以JSON格式上传至MQTT，MQTT发布开关灯指令，树莓派执行指令操作

最新资源